How to use the Spec Graph agent skill: setup and examples

What the spec-graph skill makes the agent do

An agent skill is a set of instructions that an AI agent loads when a task matches the skill's description. The spec-graph skill applies when work involves locating, reading, creating, updating or validating project specs, or when a change may alter a documented boundary, contract, invariant, behavior or architecture decision.

In that situation the skill tells the agent to look up the owning spec first, align its work with the decisions recorded there, and surface any contradiction instead of silently diverging. When a change does move a boundary or overturn a decision, the agent is told to update the spec in the same change so the specs do not drift from the code.

• Consults the relevant spec before changing a documented boundary or decision.
• Flags contradictions between a requested change and a recorded decision.
• Keeps specs current, including their status field, when a change alters them.
• Uses spec tools to search, read, create, update, delete and validate specs and their links.

Install the spec-graph skill

You can install the skill in one of two ways. The first is to download the ZIP from this page and unzip it into a skills folder. Use ~/.claude/skills/ to make it available to all your projects, or the .claude/skills/ folder inside a single project to share it with that repository.

The second is to upload the ZIP in the Claude apps. Open Settings, go to Capabilities, then Skills, and upload the file there.

The skill package contains one file, SKILL.md, so after unzipping you should see a spec-graph folder containing that file.

• Option A: download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use.
• Option B: unzip it into a project's .claude/skills/ folder to apply it to that repository.
• Option C: in the Claude apps, go to Settings → Capabilities → Skills and upload the ZIP.

Check the requirements before you rely on it

The skill assumes that the ThinkRail spec tools exist and that the repository contains spec documents. Without them the skill is not useful on its own. A spec is a markdown file whose frontmatter carries an id and a type, so the repository needs files like that, typically named SPEC.md and placed beside the module they describe.

The skill expects these tools: spec_grep, spec_get, spec_graph, spec_create, spec_update, spec_delete and spec_validate. It runs no scripts and uses no network access, according to its listing.

• ThinkRail spec tools: spec_grep, spec_get, spec_graph, spec_create, spec_update, spec_delete, spec_validate.
• A repository containing spec documents with frontmatter that includes id and type.
• The skill runs no scripts and uses no network access.

How to trigger the skill with natural requests

You do not need a special command. The skill is selected when your request matches its description, so describe the work in terms of specs, decisions and boundaries. Requests that name a boundary, a contract or an architecture decision are the most likely to load it.

For a localized fix or a quick explanation, the skill tells the agent to keep lookup minimal and read only the files it needs. If you want the spec consulted, say so explicitly.

• Check whether this change respects the spec for the auth module before you edit it.
• Find the spec that records why we chose a queue over direct database writes.
• Update the spec for the billing package, since we are moving the boundary to the new service.
• Validate the spec graph after we restructured these modules.

Example workflow: a change that moves a boundary

Suppose you ask the agent to move a module's dependency across a boundary the specs define. With the skill active, the agent follows the working order the skill sets out: orient from the module using the graph and metadata tools, read the relevant spec bodies, align the change with the recorded decisions, and surface any conflict before continuing.

If the change is accepted, the agent updates the affected spec frontmatter with spec_update, edits the prose with the normal edit tool, adds a spec_create record for any new module, and runs spec_validate to catch dangling links, duplicate ids or parent cycles.

• Orient: spec_graph for the neighbourhood, spec_get for metadata, read for the body.
• Align: reconcile the change with recorded decisions and contracts.
• Update: spec_update for frontmatter including status, edit for prose, spec_create for new modules.
• Check: run spec_validate after structural changes.

Tips for getting good results

The skill works best when the specs are short and honest. It explains that specs should capture intent and the edges that matter, not a file-by-file inventory, and that each fact should live in one spec with others linking to it by id. Keeping status current helps the agent judge whether a spec is in force, drifting or finished.

Keep requests proportional. Asking for a large architectural review will load more specs than a one-line fix needs, and the skill itself warns that reading unrelated specs adds noise.

• Keep the status field current: draft, active, stale, done or deprecated.
• Use spec_validate after moving or renaming specs.
• Ask for a narrow check when you only need one area reviewed.