Plugin Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Infrahub Skills repository functions as a Claude Code plugin, providing a collection of Markdown-based skills to guide AI assistants in Infrahub environments. The architecture contains no application code for the primary logic; instead, it uses structured Markdown to express domain knowledge, rules, and best practices.
Sources: dev/knowledges/architecture.md:3-8, README.md:162-166
Core System Components
The system relies on five primary conceptual units to deliver guidance and verify correctness:
| Concept | Description |
|---|---|
| Plugin | A packaged set of skills and hooks distributed via .claude-plugin/plugin.json. |
| Skill | A self-contained unit of domain knowledge including rules, examples, and references. |
| Rule | A specific best practice or requirement within a skill, modularized for context efficiency. |
| Hook | A trigger that automatically detects project context to activate relevant skills. |
| Evaluation | A test scenario verifying that a skill produces correct AI output. |
Sources: dev/knowledges/architecture.md:10-18
Component Hierarchy
The following diagram illustrates the structural organization of the plugin components:
Sources: dev/knowledges/architecture.md:22-44
Progressive Disclosure Model
To manage the AI context window efficiently, the architecture employs a three-level loading system. This ensures that the AI only reads detailed instructions when they are relevant to the active task.
- Level 1: Metadata (~100 words): Includes the name and description in the frontmatter. This level is always visible and triggers initial activation.
- Level 2: SKILL.md Body: Loaded upon activation. It provides the workflow, overview, and pointers to detailed files.
- Level 3: Supporting Files: Rules, examples, and references loaded on demand as needed by the agent.
Sources: dev/knowledges/architecture.md:48-65, dev/guides/adding-a-skill.md:20-29
Skill Activation Flow
This sequence shows how an agent interacts with the layered architecture during a session:
Automatic Detection and Hooks
The plugin is designed for zero-configuration by the user through the SessionStart hook. The hooks-handlers/session-start.sh script detects Infrahub project markers to provide context for skill activation.
Detection logic targets specific file markers:
- Presence of
.infrahub.ymlorinfrahub.tomlconfiguration files. - Schema files containing
version: "1.0"withnodes:orgenerics:keys.
Sources: dev/knowledges/architecture.md:101-107, hooks-handlers/session-start.sh:1-10
Modular Rule and Shared Resource System
Rules are independently addressable files, typically organized within a rules/ subdirectory for each skill. This modularity allows the AI to load only specific concerns, such as naming conventions or relationship identifiers, without consuming the entire skill set.
Shared Infrastructure
Cross-cutting concerns (e.g., GraphQL query syntax or .infrahub.yml formats) are stored in skills/infrahub-common/. While centralizing resources avoids duplication, it carries a "context cost" as every skill loading common resources pays for the full content of those shared files.
Sources: dev/knowledges/architecture.md:68-76, dev/knowledges/architecture.md:86-96
Evaluation and Grading System
The architecture includes a deterministic evaluation system to ensure guidance quality. Evaluations are defined in a root eval.yaml file and verified using grader scripts.
*eval.yaml**: A single configuration file at the project root defining tasks, prompts, and expected output descriptions.
graders/: Deterministic Python scripts that read model output and emit JSON scores.- CI Integration: CI runs
skillgradein a matrix, requiring a threshold (typically 0.8) to pass.
Sources: dev/knowledges/architecture.md:78-82, dev/guides/adding-a-skill.md:144-177
Conclusion
The Infrahub Skills architecture prioritizes Markdown-based portability and context window efficiency. By utilizing a progressive disclosure model and automated context detection, it provides domain-specific expertise to AI assistants while maintaining a lightweight, modular structure.