Agent: Implementing Skill Changes

Relevant source files

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

• .agents/skills/implementing-skill-changes/SKILL.md
• dev/guides/adding-a-skill.md
• dev/guidelines/skill-authoring.md
• dev/guidelines/skill-registration.md
• AGENTS.md
• dev/knowledges/architecture.md
• dev/guidelines/minimum-change.md
• dev/knowledges/skill-writing-guide.md
• dev/README.md

Implementing skill changes within the Infrahub Skills project involves creating or modifying structured Markdown guidance to provide AI assistants with domain-specific rules, examples, and references for infrastructure development tasks. This process is governed by a "Rule = Test" philosophy, requiring that every new guidance rule is accompanied by deterministic evaluation coverage.

Sources: dev/guides/adding-a-skill.md:3-8, AGENTS.md:188-193

Skill Architecture and Anatomy

Skills follow a specific directory structure under the skills/ directory. Each skill acts as a self-contained unit of domain knowledge.

skills/infrahub-my-skill/
├── SKILL.md              # Entry point (required)
├── examples.md           # Ready-to-use patterns
├── reference.md          # Property/format reference
└── rules/                # Modular rules by category
    ├── _sections.md      # Category index
    ├── _template.md      # Template for new rules
    ├── 01-naming-foo.md  # Individual rule files
    └── 02-structure-bar.md

Sources: dev/guides/adding-a-skill.md:12-21, dev/knowledges/architecture.md:21-36

Progressive Disclosure Model

To manage the AI context window efficiently, the system utilizes a three-level loading hierarchy:

1. Level 1: Metadata: Contained in the YAML frontmatter of SKILL.md. It includes the name and description (~100 words) and determines whether the skill triggers.
2. Level 2: SKILL.md Body: Loaded upon activation. It provides the overview, workflow, and pointers to Level 3 files.
3. Level 3: Supporting Files: Rules, examples, and references loaded on-demand as the AI processes specific tasks.

Sources: dev/guides/adding-a-skill.md:23-38, dev/knowledges/architecture.md:44-58

Implementation Workflow

The implementation process follows a strict sequence to ensure guidance is accurate, verified, and correctly registered.

This diagram illustrates the progression from identifying a need to final registration.
Sources: dev/guides/adding-a-skill.md:46-218, dev/guidelines/minimum-change.md:10-30

Step 1: Minimum Change Ladder

Before creating new files, you must evaluate the smallest artifact that closes the gap:

• Need: Verify the mistake has actually occurred multiple times.
• Existing: Link or tighten existing rules in infrahub-common or the specific skill.
• Edit: Add a single sentence to an existing rule rather than creating a new file.
• Product: Determine if the Infrahub product itself should reject the error (e.g., via validator).

Sources: dev/guidelines/minimum-change.md:10-25

Step 2: Triggering and Frontmatter

The description field in the SKILL.md frontmatter is the primary triggering mechanism. It must include the primary action and specific contexts using TRIGGER and DO NOT TRIGGER patterns.

Component	Requirement
Name	Matches the directory name (e.g., infrahub-managing-schemas).
Description	Specific trigger contexts; mentions synonyms and adjacent concepts.
Triggers	Explicitly includes triggers for modifying, debugging, and extending artifacts.
Metadata	Includes version (must match plugin.json) and author.

Sources: dev/guides/adding-a-skill.md:61-75, dev/guidelines/skill-authoring.md:18-35

Step 3: The "Rule = Test" Requirement

Every significant piece of guidance must be verifiable. A rule change is only complete when it includes:

1. The Rule file under rules/.
2. A Grader check function in graders/<skill>/lib.py.
3. An eval.yaml task.
4. A Task grader script run against at least four fixtures.
5. Regenerated evaluations/*.json via scripts/sync-evals.py.

Sources: AGENTS.md:188-195, dev/guides/adding-a-skill.md:126-170

Skill Registration

A new or modified skill must be registered across five surfaces to be visible and correctly released. Failure to update these surfaces results in a skill that is "invisible" to certain audiences.

Surface	Action
AGENTS.md	Add/Update row in the Quick Reference → Skills table.
README.md	Add/Update row in the Skills table and Project Structure tree.
docs/docs/readme.mdx	Update skills table with Docusaurus links.
docs/docs/skills-reference/	Create or update the .mdx page for the skill.
.github/.release-manifest.json	Append skill name to the skills array.

Sources: dev/guidelines/skill-registration.md:10-23, dev/guides/adding-a-skill.md:195-207

Verification Procedures

Verification ensures the prose is effective and the technical commands are valid.

1. Freshness Check: Run uv run invoke freshness to check the gap between your working tree and the installed plugin.
2. Linting: Run uv run invoke lint to execute rumdl (Markdown), yamllint (YAML), and scripts/check-cli-invocations.py.
3. Evaluations: Run skillgrade --smoke or skillgrade --eval=<task-name> to test output correctness against the rules.
4. CLI Validation: scripts/check-cli-invocations.py validates infrahubctl commands against the pinned cli_tree.py.

Sources: dev/guidelines/skill-authoring.md:112-140, AGENTS.md:94-110, dev/guides/adding-a-skill.md:214-230

Conclusion

Implementing skill changes is a disciplined process of encoding domain knowledge while ensuring every claim is verified and every change is registered. By following the progressive disclosure model and the Rule=Test requirement, authors maintain high-quality AI guidance that stays synchronized with the Infrahub platform.

Sources: dev/knowledges/architecture.md:88-112, AGENTS.md:188-210