Agent: Grilling Skill Features
Relevant source files
The following files were used as context for generating this wiki page:
The "Grilling Skill Features" workflow defines the internal process for developing and refining AI agent skills within the Infrahub ecosystem. It ensures that every new capability or rule added to the repository meets high standards of technical accuracy, deterministic verifiability, and minimal context usage. This system utilizes a "Rule = Test" philosophy, where no guidance is shipped without corresponding automated evaluation.
The architecture relies on a progressive disclosure model to manage AI context efficiently. Skills are structured as modular Markdown files, allowing agents to load only the specific rules and examples necessary for a task. This prevents context window exhaustion while providing deep domain knowledge for Infrahub development tasks like schema design and data management.
Sources: dev/knowledges/architecture.md, AGENTS.md, dev/guides/adding-a-rule.md
Skill Development Lifecycle
The lifecycle of a skill feature moves from initial identification of a gap to a verified pull request. Developers use internal agent skills like grilling-skill-features to take an idea through design, testing, and implementation.
The diagram shows the sequential pipeline for infusing new logic into the repository agents.
Sources: AGENTS.md:46-51, dev/README.md:23-28
Core Architecture: Progressive Disclosure
Skills use a three-level loading system to maintain high performance and accuracy for AI assistants. This structure ensures that the AI is not overwhelmed by irrelevant data while remaining "trigger-ready" for specific tasks.
| Level | Component | Description | Context Size |
|---|---|---|---|
| Level 1 | Metadata | Frontmatter containing name and description. Determines skill activation. | ~100 words |
| Level 2 | SKILL.md Body | Contains the overview, workflow, and pointers to other files. | <500 lines |
| Level 3 | Supporting Files | Modular rules, examples, and reference tables loaded on demand. | Unlimited |
Sources: dev/guides/adding-a-skill.md:19-33, dev/knowledges/architecture.md:39-55
Skill Anatomy
Each skill resides in its own directory under skills/ and contains specific required files:
- SKILL.md: The entry point and primary triggering mechanism.
- rules/: A directory containing modular rules (e.g.,
01-naming.md) and a_sections.mdindex. - examples.md: Fenced code blocks showing "Right" vs "Wrong" patterns.
- reference.md: Property/format tables for structured data.
Sources: dev/guides/adding-a-skill.md:7-17, dev/knowledges/architecture.md:17-34
The "Rule = Test" Requirement
A core feature of the development process is the strict requirement that every new rule must ship with automated tests. This prevents "silent rot" where skill prose drifts from actual product behavior.
The sequence shows how multiple components are synchronized to validate a single rule change.
Sources: dev/guides/adding-a-rule.md:1-12, AGENTS.md:155-171
Evaluation Components
To satisfy the "Rule = Test" requirement, developers must update four specific surfaces:
- Rule Prose: The Markdown file explaining the "Why" and "How".
- Grader Function: A deterministic Python function in
graders/<skill>/lib.pythat parses output (e.g., viaastfor Python oryaml.safe_load). - Task Definition: A new entry in
eval.yamlwith a realistic prompt and assertions. - JSON Projections: Regenerated files in
evaluations/*.jsonused by the internal runner.
Sources: dev/guides/adding-a-rule.md:14-110, dev/guides/adding-a-skill.md:95-125
Skill Registration and Release
Skills must be registered across five surfaces to be visible and functional in a release. CI does not check these surfaces, so manual verification is required.
| Surface | Requirement |
|---|---|
AGENTS.md | Add row to the Quick Reference table. |
README.md | Add to the Skills table and Project Structure tree. |
docs/docs/ | Add a new Docusaurus .mdx reference page. |
.release-manifest.json | Append name to the skills array. |
changelog/ | Create a news fragment for towncrier. |
Sources: dev/guidelines/skill-registration.md:11-20, dev/guides/adding-a-skill.md:162-178
Versioning Consistency
The metadata.version in SKILL.md must be identical across five files:
.claude-plugin/plugin.json.github/.release-manifest.jsonpyproject.toml- Every
skills/*/SKILL.mdfile uv.lock
Sources: dev/guides/adding-a-skill.md:90-93, specs/001-towncrier-release-process/plan.md:32-35
Verification and Dogfooding
Edits made to skills in the working tree are not automatically active in the agent session. Developers must use specific commands to verify changes:
- Freshness Check:
uv run invoke freshnesscompares the working tree against the installed plugin cache. - Smoke Test:
skillgrade --smokeruns the subset of evals designed for per-change validation. - Deterministic Grading: Graders must be verified against four fixtures (Compliant, Variant Compliant, Violating, and Near-Miss) to ensure they are not simply matching substrings.
Sources: AGENTS.md:121-140, dev/guides/adding-a-rule.md:173-195
Summary
Agent: Grilling Skill Features provides a robust framework for extending Infrahub's AI capabilities. By enforcing a modular architecture and a "Rule = Test" philosophy, the project ensures that AI guidance remains accurate, version-synced, and verifiable. The process moves from prose to deterministic Python graders, culminating in a multi-surface registration that prepares the feature for official release.