Installation & Setup

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• dev/knowledges/architecture.md
• pyproject.toml
• skills/infrahub-common/rules/_sections.md
• skills/infrahub-auditing-repo/rules/structure-infrahub-yml.md

Infrahub Skills provides domain-specific knowledge to AI coding assistants working with the Infrahub infrastructure management platform. The setup process configures the AI agent to recognize Infrahub project structures and apply specific rules for schema design, data modeling, and automation logic.

The system functions as a Claude Code plugin, consisting of structured Markdown files that the AI assistant consumes on demand. Proper installation ensures that hooks correctly detect Infrahub markers, such as .infrahub.yml or schema files, to activate the relevant skills automatically.

Sources: README.md:1-10, dev/knowledges/architecture.md:5-15

Prerequisites

Before installing the skills, you must ensure the environment meets the following requirements:

• Python Environment: Python version 3.10 or higher is required.
• Infrahub Instance: A running Infrahub instance is necessary for testing and loading generated resources.
• Tooling: infrahubctl must be installed to load schemas and run generators.
• AI Assistant: A coding assistant supporting skills or custom context (e.g., Claude Code, GitHub Copilot, Cursor).
• Analyst Skill Requirements: Requires a configured Infrahub MCP server.

Sources: README.md:118-125, pyproject.toml:5

Installation Methods

Automated Installation (npx)

The recommended method uses the Vercel Skills CLI to install skills across all detected AI tools.

npx skills add opsmill/infrahub-skills

The installer prompts for installation location (project-specific or global) and authorized agents. Use the --yes flag to skip interactive prompts.

Sources: README.md:5-15, README.md:129-136

Claude Code Plugin

Users of Claude Code can install directly from the OpsMill marketplace:

/plugin marketplace add opsmill/claude-marketplace
/plugin install infrahub@opsmill

Sources: README.md:138-142

Manual Setup

You can clone the repository and copy the skills/ directory directly into your Infrahub project. You must always include the infrahub-common/ directory as it contains shared dependencies.

Sources: README.md:148-154

Project Configuration

.infrahub.yml Setup

The .infrahub.yml file serves as the primary entry point for Infrahub to discover repository resources. The setup requires valid paths for all registered components.

Section	Required Fields	Description
queries	name, file_path	GraphQL query registrations
check_definitions	name, file_path	Python validation checks
jinja2_transforms	name, query, template_path	Jinja2 configuration transforms
generator_definitions	name, file_path, query, targets	Design-driven automation generators

Sources: skills/infrahub-auditing-repo/rules/structure-infrahub-yml.md:25-45

AI Tool Custom Instructions

After file installation, individual tools require configuration to point the AI to the skills directory:

• GitHub Copilot: Create .github/instructions/infrahub.instructions.md.
• Cursor: Create .cursor/rules/infrahub.mdc targeting .py, .yml, and .yaml files.

Sources: README.md:160-180

Architecture and Activation Flow

The installation sets up a session-start hook that monitors the project for specific Infrahub markers. When detected, the AI uses a progressive disclosure model to load metadata before triggering full skill content.

The diagram shows the logic used by the SessionStart hook to transition from project detection to granular skill loading.

Sources: dev/knowledges/architecture.md:20-65

Verification and Maintenance

To verify the installation, you should perform a connectivity check and run an initial audit of the project structure.

1. Check Connectivity: Run infrahubctl info to verify server reachability.
2. Environment Detection: Ensure the tool detects the correct Python prefix (e.g., uv run).
3. Run Audit: Use the command "Audit this Infrahub repo" to verify that .infrahub.yml and all file paths are correctly registered.
4. Updates: Keep skills current using npx skills update.

Sources: README.md:15-18, skills/infrahub-common/rules/_sections.md:25-30, skills/infrahub-auditing-repo/rules/structure-infrahub-yml.md:15-20

Successful installation and setup establish a robust environment where the AI coding assistant applies Infrahub-specific naming conventions, relationship patterns, and validation rules automatically. This ensures that infrastructure-as-code artifacts remain compliant with platform requirements from the moment of creation.