Skip to main content

Installation and setup

Infrahub Skills can be installed into any AI tool that supports skills or custom context files. Installation takes one command for most setups: install into a specific Infrahub repository to work in that project, or install globally to use the skills across all your projects.

Prerequisites​

  • AI coding assistant: any tool that supports the Agent Skills format or reads custom context files: Claude Code, GitHub Copilot, Cursor, Windsurf, Amp, Cline, Codex, and others
  • Infrahub instance: version 1.7 or later (earlier versions may work but are not tested). See the Infrahub installation docs for setup instructions
  • infrahubctl: required for loading generated schemas, objects, and running generators. See the infrahubctl docs
  • Infrahub MCP server (optional): required only for the Data Analyzer skill, beneficial but not required for other skills. See the MCP server docs

One .infrahub.yml section needs a newer Infrahub​

Most of .infrahub.yml works across every version above. One section does not: graphql_fragments, which lets several queries share the same GraphQL selection by name instead of repeating it. It requires Infrahub 1.9.0, which in turn requires infrahub-sdk 1.20.0.

The config model rejects unknown keys, so an older Infrahub does not skip the section. It rejects the whole .infrahub.yml file. Check your target version before adding graphql_fragments to a repository that runs an older release.

Supported AI tools​

AI ToolInstallation MethodAuto-detectionDirect Skill Invocation
Claude Code (plugin)/plugin install infrahub@opsmillYes (session hook)Yes (/infrahub:managing-schemas, etc.)
Claude Code (npx)npx skills addNoYes
GitHub Copilotnpx skills addNoNo, passive only
Cursornpx skills addNoNo, passive only
Windsurfnpx skills addNoNo, passive only
Ampnpx skills addNoNo, passive only
Clinenpx skills addNoNo, passive only
Codexnpx skills addNoNo, passive only

Auto-detection means the tool recognizes an Infrahub project and activates skills without you asking. It is a plugin feature, via the session start hook.

Direct skill invocation means calling a skill by name, for example /infrahub:managing-schemas. Available where the agent supports plugins. Every other tool is passive: it reads skill content as context when the request is relevant. For those, describe what you want and the AI applies the right skill.

Installation​

The npx installer detects which AI tools you have configured and installs the skills in the correct format for each one automatically.

npx skills add opsmill/infrahub-skills

The installer determines whether to install the skills in the current project directory or globally. If installing per-project, run the command from your Infrahub project root.

Tool-specific configuration​

After installing via npx or manual copy, some tools benefit from a small configuration file to activate the skills more reliably. These tools will use the skills without these files, but adding them improves consistency.

GitHub Copilot​

Create .github/instructions/infrahub.instructions.md in your project root:

---
applyTo: "**"
---

Use the skills in the `skills/` directory when working on Infrahub schemas,
objects, checks, generators, transforms, or menus. Each skill's SKILL.md
file describes when and how to use it.

Cursor​

Create .cursor/rules/infrahub.mdc in your project root:

---
description: Infrahub development skills for schemas, objects, checks, generators, transforms, and menus
globs: "**/*.{yml,yaml,py,gql,j2}"
alwaysApply: false
---

Use the skills in the `skills/` directory when working on Infrahub resources.
Each skill's SKILL.md file describes when and how to use it.

Windsurf​

Windsurf reads Markdown files from the project automatically. Optionally, reference the skills from .windsurfrules:

For Infrahub development tasks, use the skills in the `skills/` directory.
Each skill's SKILL.md file describes when and how to use it.

Claude Code (plugin)​

No additional configuration required after plugin install. The session hook fires on project open and provides context about available skills automatically.

MCP server setup (Data Analyzer skill)​

The Data Analyzer skill uses the Infrahub MCP server to query live data from a running instance. All other skills work without it.

See the Infrahub MCP server docs for setup instructions.

tip

Without MCP, the AI can still query Infrahub data by constructing GraphQL API calls directly. The interaction is more verbose, but functional.

Verifying the installation​

  1. Check the files are present: confirm that skills/*/SKILL.md files exist in your project directory (or globally, depending on your install method).

  2. Test skill activation: open the project in your AI tool and ask:

    What Infrahub skills do you have available?

    The AI should list the installed skills.

  3. Test skill output: ask the AI to create a small schema:

    Create a Device node with a name and status attribute.

    If the skills are active, the output should:

    • Start with version: "1.0"
    • Use kind: Dropdown for the status field with choice objects
    • Include human_friendly_id and display_label

    Without the skills, most AI assistants produce a simpler or incorrect schema that misses these conventions.

Upgrading​

npx skills update