Adding a New Skill

Relevant source files

The following files were used as context for generating this wiki page:

• dev/guides/adding-a-skill.md
• dev/guidelines/skill-authoring.md
• dev/guidelines/skill-registration.md
• dev/knowledges/skill-writing-guide.md
• dev/knowledges/architecture.md
• AGENTS.md
• dev/guidelines/minimum-change.md

A skill provides AI assistants with domain-specific rules, examples, and references for Infrahub development tasks. Each skill resides in its own directory under skills/ and adheres to the Agent Skills format.

This process involves creating a structured directory of Markdown files, defining triggers in YAML frontmatter, authoring modular rules with grading logic, and registering the skill across multiple documentation surfaces to ensure discoverability and release readiness.

Sources: dev/guides/adding-a-skill.md:3-8, dev/knowledges/architecture.md:7-20

Component Architecture and Disclosure Model

Skills utilize a three-level loading system to manage the AI context window efficiently. This progressive disclosure ensures the AI only loads detailed information when a specific task requires it.

The diagram shows the hierarchical loading model where metadata triggers the skill, the core body guides the AI, and supporting files provide technical depth on demand.
Sources: dev/guides/adding-a-skill.md:18-31, dev/knowledges/architecture.md:46-60

Skill Anatomy

A standard skill directory contains the following mandatory and optional components:

File / Directory	Status	Purpose
SKILL.md	Required	Entry point; contains frontmatter and the primary workflow.
rules/	Required	Directory containing modular, category-prefixed rules.
rules/_sections.md	Required	Category index and table of contents for rules.
examples.md	Optional	Ready-to-use patterns for the AI to adapt.
reference.md	Optional	Property and format reference tables (e.g., API parameters).

Sources: dev/guides/adding-a-skill.md:10-17, dev/knowledges/architecture.md:22-44

Implementation Procedure

1. Frontmatter and Triggering

The description field in the SKILL.md frontmatter is critical as it determines if the AI activates the skill. It should include the primary action, specific trigger contexts, and synonyms. Use TRIGGER and DO NOT TRIGGER clauses to disambiguate from neighboring skills.

---
name: infrahub-my-skill
description: >-
  Create and manage Infrahub [thing].
  Use when [specific contexts].
  TRIGGER when: [what the user says or does].
  DO NOT TRIGGER when: [what might look similar but isn't].
metadata:
  version: 1.1.0
  author: OpsMill
---

Sources: dev/guides/adding-a-skill.md:52-67, dev/guidelines/skill-authoring.md:16-28, dev/knowledges/skill-writing-guide.md:6-26

2. Rule Authoring

Rules are modular best practices. Each rule must cover exactly one concern and include a summary, the reasoning (the "why"), implementation steps, and examples.

• One Fact, One Home: State a claim in one file and point to it elsewhere to avoid drift.
• Fenced Blocks: Place compliant and non-compliant examples in separate fenced code blocks. This prevents the AI from copying the "Wrong" section into its output.

Sources: dev/guidelines/skill-authoring.md:52-59, dev/knowledges/skill-writing-guide.md:61-75

3. Evaluation and Grading

Every new rule or skill must ship with evaluation coverage to prevent silent rot.

1. Add evaluation tasks to the root eval.yaml.
2. Create deterministic grader scripts in graders/<skill-name>/ using Python.
3. Regenerate JSON projections using python scripts/sync-evals.py.

The sequence diagram illustrates the "Rule = Test" workflow where every guidance change is verified by a corresponding automated test.
Sources: dev/guides/adding-a-skill.md:109-144, AGENTS.md:204-224

Registration and Documentation

A skill is not considered "shipped" until it is registered across five mandatory surfaces. CI does not check these, so manual verification is required.

Surface	Action
AGENTS.md	Add row to the "Quick Reference → Skills" table.
README.md	Add row to "Skills" table and an entry in the "Project Structure" tree.
docs/docs/readme.mdx	Add row to the skills table.
docs/docs/skills-reference/<name>.mdx	Create a new page (remove infrahub- prefix from filename).
.github/.release-manifest.json	Append the skill name to the skills array.

Sources: dev/guidelines/skill-registration.md:8-17, dev/guides/adding-a-skill.md:168-175

Mandatory Requirements Checklist

Before submitting a Pull Request for a new skill, verify the following:

• SKILL.md frontmatter metadata.version matches .claude-plugin/plugin.json and .github/.release-manifest.json.
• Rules are organized in rules/ with a corresponding _sections.md index.
• Deterministic graders are implemented for all new tasks.
• A news fragment is created using uv run towncrier create in the changelog/ directory.
• Markdown is linted using uv run rumdl check . and YAML using yamllint.

Sources: dev/guides/adding-a-skill.md:188-212, dev/guidelines/skill-authoring.md:124-129, AGENTS.md:243-250

Conclusion

Adding a new skill requires balancing clear technical prose with strict architectural consistency and automated verification. By following the three-level progressive disclosure model and ensuring "One Fact, One Home," you maintain a maintainable and efficient knowledge base for AI agents to support Infrahub development.
Sources: dev/knowledges/architecture.md:95-103, dev/guidelines/minimum-change.md:5-10