Repo Auditor

Skill: infrahub-auditing-repo

The Repo Auditor performs a full audit of an Infrahub repository against all Infrahub best practices. It checks schema files, object files, Python components (checks, generators, transforms), .infrahub.yml registration, and project structure, then generates a report identifying issues and explaining what to fix and why.

When to use

• Before loading a new schema into a production instance
• After onboarding to verify the repository follows Infrahub conventions
• When inheriting or taking over an existing Infrahub implementation
• As a periodic quality check on an active repository
• Before opening a pull request that touches schema or automation files

What it produces

A structured audit report listing:

• Issue: what was found
• Severity: error, warning, or info
• Location: file and line where possible
• Recommended fix: what to change and why

Issues are grouped by category so the most critical problems are addressed first.

Example prompts

• "Audit this repo before we deploy it"
• "I just inherited this Infrahub project — does it follow conventions?"
• "Review this repo for issues before I open a pull request"
• "Run a full audit and tell me what's wrong"

Key rules enforced

• Read-only: the audit never writes to the tree or the index; its only output is AUDIT_REPORT.md, and no destructive git command runs, even to undo the audit's own side effect
• Every reference site, not just one: a finding names the complete set of places to change, not a partial list presented as if it were complete
• Proposed syntax is verified, not inferred: a suggested filter or fix is checked against the actual schema and the audited version, not assumed from a sibling query or the latest docs
• Registration is checked, not assumed: every Python component, query, and template is cross-referenced against .infrahub.yml; an unregistered file is dead code the platform never imports
• watch dependencies are checked: a missing or incomplete watch list on a transform or generator is flagged, since it re-fingerprints on every commit or silently stops re-running
• Tree condition is stated in the report: if the audited tree had uncommitted changes, that's recorded, because it bounds what the findings are worth

Common mistakes it catches

Mistake	What the skill does instead
A check, generator, or transform file with no .infrahub.yml registration	Flags it: the platform never imports an unregistered file, so it silently never runs
A query name typo between the .gql file and the Python class	Cross-references the names and flags the mismatch before it fails at proposed-change time
Uncommitted Python or query changes	Flags them, since Infrahub syncs from the git ref, not the working tree
Bootstrap data placed under objects/	Flags it, since every sync re-imports and overwrites edits made through the UI
A Python transform or generator with no watch dependency declaration	Flags the missing key, which otherwise re-fingerprints the definition on every commit
A proposed fix based on a sibling query rather than the schema itself	Verifies the filter or syntax against the actual schema and version before proposing it

What it checks

Project structure

• Required files present (.infrahub.yml, schema files)
• Directory conventions followed
• File naming patterns (numeric prefixes on object files, snake_case on Python files)

Schema

• Naming conventions (namespace, node name, attribute name lengths and casing)
• Attribute types (no deprecated String, correct use of Dropdown, Text, Number, etc.)
• Relationship identifiers (both sides match)
• Relationship peer references (full namespace+name)
• human_friendly_id present on all nodes
• display_label present and syntactically correct
• Hierarchy configuration (correct parent/children setup for hierarchical generics)

Object files

• Correct apiVersion, kind: Object, spec structure
• Value mapping (correct use of value:, dropdown names vs. labels)
• Load order (no forward references)
• Relationship references match existing node human_friendly_id values

Python components

• InfrahubCheck: validate() signature, log_error() vs log_info() usage, error collection pattern
• InfrahubGenerator: allow_upsert=True, delete_unused_nodes=True, async generate() method
• InfrahubTransform: correct return types, data variable usage in Jinja2 templates

Cross-references and registration

• Every Python component referenced in .infrahub.yml exists as a file
• Every .gql query referenced in Python classes exists as a file
• Query names match between .gql files and Python class attributes
• Artifact definitions reference existing transforms

Best practices

• display_label caching patterns for nodes with parent relationships
• Python environment detection configuration
• Git integration setup
• watch dependency declarations on Python transforms and generators: a missing key re-fingerprints the definition on every commit, and an incomplete list silently under-regenerates

YAGNI / cost-to-fix

Beyond correctness, the auditor flags places where a from-scratch schema, Python, or denormalized data is doing work a cheaper option already handles (an off-the-shelf marketplace schema or a built-in Infrahub layer), for example:

• Any domain hand-rolled from scratch when the Infrahub Marketplace already publishes it: the auditor flags common marketplace-published domains (DCIM, location, organization, circuits, cabling) via an offline signature heuristic, so reuse them with infrahubctl marketplace get <namespace>/<name> and inherit_from instead of redefining the model
• A check that re-implements a uniqueness, presence, or allowed-values rule the schema can enforce as a constraint
• A Python transform that only formats strings, where a Jinja2 template would do
• A generator that hardcodes data belonging in objects/, reinvents a built-in IPAM/VLAN primitive, or hand-rolls subnet/IP/VLAN/port allocation instead of using a resource pool
• A Profile containing a single never-varying value that an attribute default_value would cover, or a generate_profile/generate_template flag enabled with no consumer in the repo
• A generator that stamps a fixed structure an Object Template could clone, or an Object Template used to push shared values (or a Profile used to clone structure), the wrong tool for the job in each case

These findings are advisory: the code works as-is, but the cheaper option is less to maintain and stays aligned with the platform. Each one names the specific layer to move to, and they are ranked by how cheap the fix is: reusing a published marketplace schema is the cheapest win of all and ranks first, above a one-line schema change, which ranks above a full rewrite.

Acting on the results

Severity	Meaning	Action
Error	Will cause load failures or runtime errors	Must fix before loading into Infrahub
Warning	Convention violation that may cause confusing behavior	Should fix
Info	Suggestion for improvement	Optional

Cost-to-fix (YAGNI) findings are always advisory: they never block a load. They are listed cheapest-fix-first, so start with the ones that cost the least, and each names the specific replacement to apply.

The Repo Auditor can be asked to fix issues directly after reporting them: describe which issues to address and the AI applies the relevant skill to make the corrections.