Skip to content
Get packs

Spec Graph

Lets an agent find, read, create, update and validate project specification documents that record architecture decisions and boundaries.

Source Download skill
Repository
JetBrains/thinkrail
Stars
7,089
Licence
Apache-2.0
Files
1 file

What it does

This skill teaches an AI agent to treat a project's specification documents as the authoritative record of its architecture, decisions, contracts and boundaries. Before changing code that touches a documented boundary or decision, the agent looks up the relevant spec, aligns its work with it, and flags contradictions instead of silently diverging. It also keeps specs up to date when a change alters them, and uses dedicated tools to manage the spec graph and check it for broken links.

Great for

  • Engineering teams using the ThinkRail spec-graph system to keep architecture documentation in sync with code
  • Developers working in a repository with SPEC.md files who want an agent to respect recorded decisions
  • Maintainers who want agents to update specs as part of the same change that moves a boundary

Skip it if

  • Projects without any spec documents or the spec_* tools, since the skill assumes that tooling exists and is not useful on its own
  • Quick one-off scripts or localized fixes, where the skill itself says lookup should stay minimal (reading unrelated specs adds noise)

Try asking

  • “Before changing the public API of the billing module, check which spec governs its contract and align the change with it”
  • “Explain the dependency boundaries of the auth package using its spec graph”
  • “Create a new module-design spec for a newly added package and validate the links”
  • “Check whether my refactor contradicts any recorded architecture decision and update the spec if it does”
Step-by-step guide: how to use Spec GraphInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 1 original files, the Apache-2.0 licence and an attribution note.

    spec-graph.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip spec-graph.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip spec-graph.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Point the agent at a specific module or root spec so it orients on the right neighborhood instead of scanning the whole graph.
  • Ask the agent to run spec_validate after it restructures specs to catch dangling links and duplicate ids.
  • Install the ThinkRail tooling first; this SKILL.md alone only describes the workflow and cannot read specs without those tools.

What's inside

  • SKILL.md

Redistributed unmodified from JetBrains/thinkrail under the Apache-2.0 licence. The assessment was drafted with AI from the skill's files on 2026-11-02. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.