SKILL.md
Infrahub Repo Auditor
Overview
Comprehensive audit of an Infrahub repository against all rules and best practices from the infrahub-skills plugin. Produces a structured report covering schemas, objects, checks, generators, transforms, menus, .infrahub.yml configuration, and deployment readiness.
Project Context
Project structure: !find . -maxdepth 2 -type f \( -name ".yml" -o -name ".yaml" -o -name ".py" -o -name ".gql" -o -name "*.j2" \) 2>/dev/null | head -40
Infrahub config: !cat .infrahub.yml 2>/dev/null || echo "No .infrahub.yml found"
When to Use
- Before deploying a repository to Infrahub
- When onboarding to an existing Infrahub project
- After significant refactoring to catch regressions
- As a periodic quality gate in development workflows
- When troubleshooting schema loading, object sync,
or pipeline failures
How It Works
When invoked, the auditor:
- Discovers the project structure
(.infrahub.yml, schemas, objects, checks, generators, transforms, menus)
- Validates each component against the rules
defined in the infrahub-skills plugin
- Cross-references between components (e.g.,
query names match between Python files and .infrahub.yml)
- Generates a markdown report with findings organized by severity
The phased procedure that ties these steps together lives in [audit-procedure.md](./audit-procedure.md) — read that file when running an audit. It defines the nine phases (project structure → schema → objects → Python components → cross-references → registration → best practices → deployment → YAGNI / cost-to-fix) and the per-finding severity levels used in the final report.
Audit Categories
| Priority | Category | What It Checks |
|---|---|---|
| CRITICAL | Project Structure | .infrahub.yml exists, paths valid |
| CRITICAL | Schema Validation | Naming, relationships, deprecated fields |
| CRITICAL | Object Validation | YAML structure, value types, refs |
| CRITICAL | Python Components | Class inheritance, required methods |
| HIGH | Cross-References | Query names match, target groups |
| HIGH | Relationships | Bidirectional IDs, cardinality |
| HIGH | Registration | All files registered, no orphans |
| MEDIUM | Best Practices | humanfriendlyid, display_label |
| MEDIUM–LOW | YAGNI / Cost-to-Fix | Python doing what schema, GraphQL, Jinja2, or built-in IPAM/VLAN can do; denormalized data; un-extracted duplicate shapes; a whole domain hand-rolled when the marketplace ships it. Severity tracks the cost-to-fix ladder: steps 1–3 MEDIUM, steps 4–7 LOW |
| MEDIUM | Deployment | Git status, bootstrap placement |
| LOW | Patterns & Style | Code organization, naming |
Running the Audit
Tell Claude: "Audit this Infrahub repo" or "Run the Infrahub repo auditor"
The auditor will scan the current working directory, walk the phases defined in [audit-procedure.md](./audit-procedure.md), and produce the report described below.
Report Format
The report is written to AUDIT_REPORT.md in the project root with this structure:
# Infrahub Repository Audit Report
## Summary
- Total findings: N
- Critical: N | High: N | Medium: N | Low: N | Info: N
## Project Structure
...
## Schema Audit
...
## Object Data Audit
...
## Checks Audit
...
## Generators Audit
...
## Transforms Audit
...
## Menus Audit
...
## Cross-Reference Integrity
...
## Deployment Readiness
...
## YAGNI / Cost-to-Fix Findings
Findings sorted by `ladder_step` ascending (cheapest
fix first), then by file path. Each entry names the
rule, the ladder step, the file:line, and the
suggested replacement (schema feature, GraphQL query,
Jinja2 template, `Builtin*`/`Ipam*` inheritance, or
inverse relationship declaration).
...Audit Rules Reference
The auditor checks rules from all skills:
- [../infrahub-managing-schemas/](../infrahub-managing-schemas/) -- Naming,
relationships, attributes, hierarchy, display, extensions, uniqueness, migration
- [../infrahub-managing-objects/](../infrahub-managing-objects/) -- Format,
values, children, ranges, organization
- [../infrahub-managing-checks/](../infrahub-managing-checks/) --
Architecture, Python class, API, registration
- [../infrahub-managing-generators/](../infrahub-managing-generators/) --
Architecture, Python class, tracking, API
- [../infrahub-managing-transforms/](../infrahub-managing-transforms/) --
Types, Python/Jinja2, hybrid, artifacts, API
- [../infrahub-managing-menus/](../infrahub-managing-menus/) -- Format,
item properties, hierarchy, icons
- [../infrahub-common/](../infrahub-common/) -- Git integration,
caching, .infrahub.yml reference, GraphQL
- [../infrahub-common/rules/workflow-information-priority.md](../infrahub-common/rules/workflow-information-priority.md)
-- Skill content first; how to consult docs.infrahub.app on a genuine gap (e.g. deleting nodes)
Rules and Procedure
- [audit-procedure.md](./audit-procedure.md) — the
nine-phase walkthrough that drives every audit run
- [rules/](./rules/) — detailed audit rule
definitions referenced from the phases
- [examples.md](./examples.md) — sample audit
reports and finding patterns