New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Official agent skill

Spec Graph

by JetBrains in JetBrains/thinkrail

A skill your agent uses when locating, reading, creating, updating, or validating project specs, or when work is governed by or may alter a documented boundary, contract, invariant, behavior, or…

OfficialApache-2.0Auto-check passedDevelopment

Install Spec Graph

skills CLI
$ npx skills add JetBrains/thinkrail --skill spec-graph -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install JetBrains/thinkrail spec-graph --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/JetBrains/thinkrail.git skills-src && mkdir -p .claude/skills && cp -r skills-src/packages/spec-graph/skills/spec-graph .claude/skills/spec-graph && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
spec-graph
GitHub stars
513
Token cost
~1.4k tokens
SKILL.md length
769 words
Files
1
Skills in repo
11
Repo updated
First seen
Licence
Apache-2.0

At a glance

A skill your agent uses when locating, reading, creating, updating, or validating project specs, or when work is governed by or may alter a documented boundary, contract, invariant, behavior, or…

  • Works in 4 steps: Orient when specs govern the work. From… → Align. Reconcile the change with the… → Update. When the change alters a… → …
  • Validating project specs
  • SKILL.md covers Specs are the ground truth, What a spec is, The graph and Frontmatter, plus 2 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Spec Graph is an agent skill from JetBrains/thinkrail, published by the product's own GitHub organization. Use when locating, reading, creating, updating, or validating project specs, or when work is governed by or may alter a documented boundary, contract, invariant, behavior, or architecture decision.

Its SKILL.md is about 1.4k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Development. The repository describes itself as: Vibe code with pi in a lightweight, real IDE that customises itself around the way you work — The Vibe You Need. The licence is Apache-2.0.

When your agent uses it

  • Validating project specs
  • Work is governed by
  • May alter a documented boundary
  • Architecture decision

Example prompts

  • “/spec-graph”

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

  1. Orient when specs govern the work. From a known root or the module you are touching, use
  2. Align. Reconcile the change with the decisions and contracts the specs record; surface
  3. Update. When the change alters a boundary, contract, or decision, update the spec — frontmatter
  4. Check. Run spec_validate after structural changes.

What it can do on your machine

Read from SKILL.md and the folder at commit 3f7e0d4. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Spec Graph loads about 1.4k tokens when it runs. Until then it costs about 52 tokens; SKILL.md has 769 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~52
When it runs · the whole SKILL.md, loaded when a task matches
~1.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from JetBrains/thinkrail at commit 3f7e0d4, republished under its Apache-2.0 licence (© JetBrains). 769 words, ~1,356 tokens.

Download SKILL.mdSave it as .claude/skills/spec-graph/SKILL.md (or your agent's skills folder).
name
spec-graph
description
Use when locating, reading, creating, updating, or validating project specs, or when work is governed by or may alter a documented boundary, contract, invariant, behavior, or architecture decision.

Spec graph

Specs are the ground truth

  • Specs describe the architecture, decisions, contracts, and boundaries behind the code — the intent that the code alone does not reveal. Treat them as authoritative.
  • Consult the owning spec when it governs the work. When work depends on, checks, explains, or may alter a documented boundary, contract, invariant, behavior, or architecture decision, use spec_grep / spec_get / spec_graph to find the applicable record and align with it. If a change contradicts a recorded decision, surface and reconcile the contradiction rather than silently diverging.
  • Keep lookup proportional. Specs are the map for decisions and boundaries; code confirms the implementation. A localized fix, explanation, or check that changes no documented decision may inspect only the files it needs without reading unrelated specs.
  • Keep them honest. A change that moves or blurs a boundary, or overturns a decision, updates the spec as part of the same change. Specs that drift from the code stop being ground truth.

What a spec is

  • A durable, declarative document. It states the world as it is — the intent, decisions, contracts, and boundaries behind the code — not plans, tasks, phases, or a work journey.
  • Concise and readable. It captures what is not obvious from the code; it never restates the code.
  • The bar: reading the relevant specs should be enough to understand an area and to formulate a task to improve it.
Keep specs lean
  • Explain intent, not inventory. Describe what a module is for, what it owns, and where its boundaries are — not a file-by-file transcript of its directory. The reader can see the files; the spec exists for what the files don't say.
  • Record the edges that matter. State the module's boundary (allowed / forbidden deps) and the dependency edges between its sub-modules. List a part only when its role or its edges aren't obvious from its name — e.g. a small table that carries a real dependency DAG earns its place; a table that just pairs foo.ts with "the foo tool" is noise, so say it in a sentence instead.
  • Say each thing once. A fact lives in exactly one spec; others link to it by id rather than restate it. If a paragraph is being copied between specs, move it to the spec that owns the concept and point at it. Duplicated prose drifts and turns into contradictions.
  • Prefer prose to exhaustive tables, and cut anything that only paraphrases code, filenames, or a sibling spec.

The graph

  • parent links form a hierarchy that mirrors the code structure: a SPEC.md sits beside the module it describes (fractal — a package and its sub-directories each have one), and root documents sit at the repository root.
  • depends-on, references, and implements form a dependency layer across the tree.
Show full SKILL.md (318 more words)Show less

Frontmatter

  • Required: id (a unique slug), type, title.
  • Optional: status (lifecycle), parent (single link), depends-on / references / implements (link lists), covers, tags.
  • A file is a spec when its frontmatter carries id and type.
  • status tracks a spec's lifecycle: draft (being written) → active (in force), then stale (drifting from the code), done, or deprecated. It's optional, but keep it current as a spec firms up or ages.
  • Types:
    • goal-and-requirements — the product goal and scope; the root of the graph.
    • architecture-design — system-wide topology, cross-cutting decisions, and invariants.
    • module-design — a package or module's responsibility and boundary.
    • submodule-design — the same, for a directory-level module inside a package.
    • task-spec — a temporary working document for a piece of work; not durable, and removed once the work lands.

Tools

Read:

  • spec_grep — search within specs (content, narrowed by metadata filters).
  • spec_get — a spec's frontmatter, its resolved links, and its path. Read the body with the normal read tool using that path.
  • spec_graph — a bounded slice of the graph: a subtree, ancestors, or a node's neighbors, to a depth.

Manage:

  • spec_create — a new spec with scaffolded frontmatter and headings.
  • spec_update — a spec's frontmatter (fields and links). It does not touch the body.
  • spec_delete — remove a spec.
  • spec_validate — report dangling links, duplicate ids, and parent cycles.

Prose is written and edited with the normal write/edit tools; the spec tools own frontmatter and structure.

Working with specs

  1. Orient when specs govern the work. From a known root or the module you are touching, use spec_graph for the neighborhood, spec_get for a node's metadata, and read for its body. Use spec_grep to find specs by content.
  2. Align. Reconcile the change with the decisions and contracts the specs record; surface contradictions before diverging.
  3. Update. When the change alters a boundary, contract, or decision, update the spec — frontmatter (including status) with spec_update, prose with edit — and add spec_create for a new module.
  4. Check. Run spec_validate after structural changes.

© JetBrains, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

Just SKILL.md in packages/spec-graph/skills/spec-graph of JetBrains/thinkrail.

Open the folder on GitHubat commit 3f7e0d4

Compare with similar skills

Spec Graph next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Spec Graph compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Spec Graph this skillJetBrains/thinkrail513—~1.4kAutomated safety check: PassApache-2.0
Vercel Composition Patternssupabase/supabase111k59 repos~726Automated safety check: PassMIT
Finishing a Development Branchobra/superpowers296k5 repos~1.9kAutomated safety check: PassMIT
Typescript Advanced Typesrolling-scopes/rsschool-app10k25 repos~4.2kAutomated safety check: PassMPL-2.0
PR Babysitteropeninterpreter/openinterpreter69k3 repos~4.2kAutomated safety check: PassApache-2.0
Code Review ChecklistshareAI-lab/learn-claude-code78k5 repos~1.1kAutomated safety check: PassMIT

Similar skills

  • Vercel Composition Patterns

    supabase/supabase

    Official

    React composition patterns that scale. An agent skill from supabase/supabase.

    111k GitHub starsUsed in 59 repos~726 tokens
    DevelopmentAuto-check passed

  • Finishing a Development Branch

    obra/superpowers

    Walks the last step of a branch: confirm tests pass, detect the git environment, ask how to integrate, carry out your choice and clean up the worktree.

    296k GitHub starsUsed in 5 repos~1.9k tokens
    DevelopmentAuto-check passed

  • Typescript Advanced Types

    rolling-scopes/rsschool-app

    Master TypeScript's advanced type system including generics, conditional types, mapped types, template literals, and utility types for building type-safe applications.

    10k GitHub starsUsed in 25 repos~4.2k tokens
    DevelopmentAuto-check passed

  • PR Babysitter

    openinterpreter/openinterpreter

    Watches an open GitHub pull request until it merges, handling review comments, diagnosing CI failures and retrying flaky checks along the way.

    69k GitHub starsUsed in 3 repos~4.2k tokens
    DevelopmentAuto-check passed

  • Code Review Checklist

    shareAI-lab/learn-claude-code

    Reviews code against a five-part checklist covering security, correctness, performance, maintainability and testing, and reports findings in a fixed format.

    78k GitHub starsUsed in 5 repos~1.1k tokens
    DevelopmentAuto-check passed

  • Greploop

    onyx-dot-app/onyx

    Iteratively improves a PR (GitHub), MR (GitLab), or shelved changelist (Perforce) until Greptile gives it a 5/5 confidence score with zero unresolved comments.

    32k GitHub starsUsed in 4 repos~3.3k tokens
    DevelopmentAuto-check passed

More from JetBrains/thinkrail

All 11 skills in this repo

  • Importing A Codebase

    JetBrains/thinkrail

    Official

    A skill your agent uses when asked to create the initial spec graph for an existing codebase that has source code but no specs.

    513 GitHub stars~1.6k tokensUpdated today
    Auto-check passed

  • Starting A New Project

    JetBrains/thinkrail

    Official

    A skill your agent uses when the workspace is empty, has no code, and the user brings a raw project idea.

    513 GitHub stars~1.4k tokensUpdated today
    Auto-check passed

  • Asking User Questions

    JetBrains/thinkrail

    Official

    A skill your agent uses when composing an askuserquestion round inside a workflow, or when a workflow skill names it at a question step.

    513 GitHub stars~1.9k tokensUpdated today
    Auto-check passed

  • Setting Up A Project

    JetBrains/thinkrail

    Official

    A skill your agent uses when asked to set up, onboard, initialize, or spec a project with no spec graph, or when invoked by the app's Set-up-project card.

    513 GitHub stars~500 tokensUpdated today
    Auto-check passed

  • Shipping A PR

    JetBrains/thinkrail

    Official

    A skill your agent uses when finished work needs to ship as a pull request, or when creating, syncing, updating metadata, checking status, monitoring CI, or addressing review comments on a PR.

    513 GitHub stars~1.1k tokensUpdated today
    Auto-check passed

  • Todos

    JetBrains/thinkrail

    Official

    A skill your agent uses when the user asks for a shared plan, a task needs at least three substantive execution steps, or a loose TODO is pending.

    513 GitHub stars~3.2k tokensUpdated today
    Auto-check passed

Categories

Questions about Spec Graph

What does Spec Graph do?

A skill your agent uses when locating, reading, creating, updating, or validating project specs, or when work is governed by or may alter a documented boundary, contract, invariant, behavior, or…. Spec Graph is an agent skill from JetBrains/thinkrail, published by the product's own GitHub organization. Use when locating, reading, creating, updating, or validating project specs, or when work is governed by or may alter a documented boundary, contract, invariant, behavior, or architecture decision.

When should I use Spec Graph?

Spec Graph fits situations like: validating project specs; work is governed by; may alter a documented boundary; architecture decision.

How do I install Spec Graph in Claude Code?

Run `npx skills add JetBrains/thinkrail --skill spec-graph -a claude-code`. Or copy the skill folder (packages/spec-graph/skills/spec-graph in JetBrains/thinkrail) into .claude/skills/spec-graph in your project. Claude Code loads it when a task matches its description.

How do I install Spec Graph in Codex?

Run `npx skills add JetBrains/thinkrail --skill spec-graph -a codex`. Or copy the skill folder (packages/spec-graph/skills/spec-graph in JetBrains/thinkrail) into .agents/skills/spec-graph in your project. Codex loads it when a task matches its description.

Can I use Spec Graph in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add JetBrains/thinkrail --skill spec-graph -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/spec-graph, .gemini/skills/spec-graph, .github/skills/spec-graph and .opencode/skills/spec-graph in your project.

What does Spec Graph need to run?

SKILL.md names no scripts, command-line tools or credentials: Spec Graph is instructions for the agent only.

Does Spec Graph access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Spec Graph safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Spec Graph use?

Spec Graph is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Spec Graph use?

About 1.4k tokens (SKILL.md is roughly 5.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Spec Graph?

Skills that share tags, products or a category with Spec Graph: Vercel Composition Patterns (supabase/supabase, 111k stars), Finishing a Development Branch (obra/superpowers, 296k stars), Typescript Advanced Types (rolling-scopes/rsschool-app, 10k stars) and PR Babysitter (openinterpreter/openinterpreter, 69k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Spec Graph?

JetBrains (a GitHub organization, an official publisher) maintains it in JetBrains/thinkrail, which has 513 GitHub stars. The repository holds 11 skills in this directory. The repository was last updated on October 7, 2026.

Source: JetBrains/thinkrail on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.