Infisical AI Skills

Infisical AI Skills

Give your AI coding agent accurate knowledge about Infisical — the open-source secret management platform.

Recommended: Connect our Docs MCP

The fastest way to stop your AI from hallucinating about Infisical is to connect our docs MCP server. It works with any MCP-compatible agent, auto-updates when our docs change, and requires zero maintenance.

URL: https://infisical.com/docs/mcp

Claude Code:

claude mcp add --transport http infisical-docs https://infisical.com/docs/mcp

Cursor / Windsurf: Add to your MCP settings:

{
  "mcpServers": {
    "infisical-docs": {
      "url": "https://infisical.com/docs/mcp"
    }
  }
}

VS Code / Copilot: Add to .vscode/mcp.json:

{
  "servers": {
    "infisical-docs": {
      "url": "https://infisical.com/docs/mcp"
    }
  }
}

Any MCP-compatible client can connect with that URL.

Alternative: Agent Skills

If your tool doesn't support MCP, or you want offline/local context, you can install these skills instead. They follow the Agent Skills open standard and work across 45+ AI tools.

Universal install

npx skills add Infisical/ai-skills

Claude Code (plugin marketplace)

/plugin marketplace add Infisical/ai-skills

Manual

Copy skill folders from skills/ into your project's agent skills directory:

What's included

17 skills across the whole Infisical platform. Each declares what it is not, so an agent lands on the right one — see AGENTS.md for the router and disambiguation table.

Secrets delivery

Moving and generating credentials

Other products

Platform and governance

Eval results

Every skill is A/B tested against a no-context baseline. We also ran a head-to-head comparison of Skills vs the Docs MCP. See evals/ for full data.

Skills vs no context

Skills vs MCP vs no context

Both approaches dramatically reduce hallucination. The MCP is recommended because it auto-updates with the docs and requires no maintenance.

Accuracy audit: stale skills are worse than no skill

The skills are periodically re-verified against the Infisical codebase. The most recent audit ran a three-arm regression eval — no skill, pre-audit skill, post-audit skill — with tools disabled so the model could not look anything up:

The pre-audit skills scored below the no-skill baseline. Outdated specifics don't merely fail to help — they override correct model knowledge. On the secret-syncs case the base model scored 5/5 unaided and the stale skill pulled it down to 2/5.

This is the strongest argument for the MCP: it tracks the docs automatically, so it cannot drift the way a vendored copy can. If you do install the skills, pin a version and re-pull when Infisical ships new providers or auth methods. Full data and a reproducible harness live in evals/accuracy-audit-2026-08/.

New skills

The 10 skills added in the 7 → 17 expansion, A/B tested the same way:

Null results are recorded, not hidden: on App Connections the base model already scored 4/4 unaided. The skills matter most where the model has little knowledge — PAM and SSO scored 1/5 unaided, and the Kubernetes Operator 0/5, because unaided it reaches for the legacy v1alpha1 InfisicalSecret CRD instead of current v1beta1. See evals/new-skills-2026-08/.

Generated reference files

The App Connection facts — 83 connections × auth methods × credential fields, and all 94 API endpoints — are generated from the Infisical source, not hand-maintained:

python3 tools/generate-app-connection-refs.py          # regenerate
python3 tools/generate-app-connection-refs.py --check  # CI: fail on drift

This is the structural answer to the drift problem above. Facts are derived; only guidance is written by hand. Re-verification is regenerate && git diff.

Routing: does the right skill get picked?

With 17 skills, mis-routing becomes the dominant failure mode — a skill loaded for the wrong question answers confidently from the wrong frame. So every skill declares what it is not, and AGENTS.md carries a router plus a disambiguation table for the pairs that get confused.

Measured on 14 prompts sitting deliberately on a seam between two similar skills:

Getting there took two passes. Initially descriptions alone scored 13/14 — asked about short-lived SSH certificates it chose infisical-pam, plausible but wrong, since SSH certificates come from SSH dynamic secrets. The fix was moving the boundaries into the description frontmatter, because that is what actually decides whether a skill loads. See evals/routing-2026-08/.

Why this exists

AI coding agents frequently get Infisical details wrong:

These skills correct all of that.

Contributing

To add a new skill:

1. Create a directory under skills/ with a SKILL.md and optional references/ folder
2. Create a matching plugin wrapper under plugins/ with a .claude-plugin/plugin.json
3. Add a plugin entry in .claude-plugin/marketplace.json
4. Update AGENTS.md — add it to the router table, and add a row to the disambiguation table if it sits near an existing skill
5. Put the boundary in two places: a short "not for X (other-skill)" clause at the end of the description frontmatter — that is what decides whether the skill loads — and a ## Not this skill section in the body, with reciprocal rows on the neighbours it could be confused with
6. Run claude plugin validate . to check for errors
7. Add eval cases and run A/B benchmarks (see evals/ for examples)

Keeping skills accurate

Skill content is a vendored snapshot of a moving codebase, and the accuracy audit showed a drifted skill performs worse than no skill. When re-verifying:

• Cite the source, not the docs prose. Counts and enum values come from the code: secret-sync-enums.ts, dynamic-secret/providers/models.ts, db/schemas/models.ts (IdentityAuthMethod), server/routes/v4/. Docs pages lag; enums don't.
• Prefer exact literals over prose descriptions. repository-environment beats "the environment scope". Wrong literals are the failure mode that hurts most.
• Re-sync the plugin wrappers. plugins/<name>/skills/<name>/ is a copy of skills/<name>/; they drift silently. Diff them before committing.
• Run the regression eval. evals/accuracy-audit-2026-08/run_evals.py compares no-skill / old-skill / new-skill with tools disabled. Add assertions for whatever you just corrected so the next audit catches a regression.

License

MIT