AI Agents

Stategraph is built to be driven by AI agents (Claude Code, agents using skills.sh, or any tool that loads SKILL.md files), not just humans. The integration surface is a set of skill files in github.com/stategraph/skills that teach the agent the Stategraph workflows, the safe defaults, and the canonical command form.

Available skills

Six skills, one of which is a router that dispatches to the others.

Skill Purpose
stategraph Router. Detects Stategraph tasks and dispatches to one of the five workflow skills below.
stategraph-query Read-only SQL queries, state summaries, inventory, blast radius, and gap analysis.
stategraph-cost Cost intelligence: state/tenant cost, attribution by tag/provider, cost history, coverage gaps, and plan-time cost deltas.
stategraph-change stategraph tf plan, stategraph tf apply, state deletion, transaction lifecycle.
stategraph-import Import .tfstate or HCL into Stategraph. Wire a Terraform repo to Stategraph.
stategraph-refactor Interactive address-rewrite workflow. Restructure a repo while preserving state addresses.

The router pattern means users typically only need the top-level stategraph skill installed. When the agent detects a Stategraph task, the router selects the right workflow skill and hands off via the agent's Skill tool.

Installing all six together also makes each workflow directly addressable: /stategraph-query, /stategraph-cost, /stategraph-change, /stategraph-import, /stategraph-refactor.

Install

With the skills CLI:

npx skills add stategraph/skills

Or install a specific skill:

npx skills add stategraph/skills -s stategraph-query

Manual install (Claude Code)

Clone into ~/.claude/skills/ so each skill lands at ~/.claude/skills/<name>/SKILL.md:

git clone https://github.com/stategraph/skills /tmp/stategraph-skills
cp -r /tmp/stategraph-skills/skills/* ~/.claude/skills/
rm -rf /tmp/stategraph-skills

Requirements

  • The Stategraph CLI on your PATH. See CLI installation.
  • A configured tenant. stategraph info should succeed.

Usage

Once installed, ask the agent anything Stategraph-related and the router picks the workflow:

  • "What S3 buckets do we have?" runs stategraph-query
  • "How much does this tenant cost, broken down by team?" runs stategraph-cost
  • "Plan these changes." runs stategraph-change
  • "Import this terraform.tfstate." runs stategraph-import
  • "Refactor this repo into child modules without losing state." runs stategraph-refactor

You can also invoke a workflow directly with /stategraph-query, /stategraph-cost, /stategraph-change, /stategraph-import, or /stategraph-refactor.

Safety model

Two layers, one in the skill files and one in Stategraph itself.

Skill-level: read-only vs mutating. The stategraph-query and stategraph-cost skills are read-only by design. They run SQL queries, inventory summaries, and cost reports, and never call tf plan, tf apply, imports, or refactors (stategraph-cost's only write is triggering a cost recalculation, never an infrastructure change). The other three workflow skills — change, import, and refactor — are mutating, each scoped to its own workflow.

Stategraph-level: plan and apply are gated independently. Issue an agent an API token scoped to plan only, and the worst case from a confused model is a wrong plan you throw away. There is no path from a confused model to a destroyed database. For autonomous overnight runs, plan-only is the right default. For agents that have already passed a review boundary (a CI runner on a green PR, for example), issue plan and apply.

See Authentication for token scoping.

See also