infrahub-auditing-repo - SKILL.md Agent Skill

name: infrahub-auditing-repo description: >- Audits an Infrahub repository against best practices and rules, producing a structured compliance report. TRIGGER when: reviewing repo for compliance, onboarding to existing project, pre-deployment validation, catching issues. DO NOT TRIGGER when: creating schemas, writing checks/generators, querying live data, populating objects. context: fork allowed-tools: - Read - Bash - Grep - Glob argument-hint: "[focus-area]" metadata: version: 1.2.7 author: OpsMill

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 — read that file when running an audit. It defines the eight phases (project structure → schema → objects → Python components → cross-references → registration → best practices → deployment) 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	human_friendly_id, display_label
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, 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

...

Audit Rules Reference

The auditor checks rules from all skills:

../infrahub-managing-schemas/ -- Naming, relationships, attributes, hierarchy, display, extensions, uniqueness, migration
../infrahub-managing-objects/ -- Format, values, children, ranges, organization
../infrahub-managing-checks/ -- Architecture, Python class, API, registration
../infrahub-managing-generators/ -- Architecture, Python class, tracking, API
../infrahub-managing-transforms/ -- Types, Python/Jinja2, hybrid, artifacts, API
../infrahub-managing-menus/ -- Format, item properties, hierarchy, icons
../infrahub-common/ -- Git integration, caching, .infrahub.yml reference, GraphQL

Rules and Procedure

audit-procedure.md — the eight-phase walkthrough that drives every audit run
rules/ — detailed audit rule definitions referenced from the phases
examples.md — sample audit reports and finding patterns