Agent skills

Install the SpecsGraph skills so Claude Code, Cursor, Codex or GitHub Copilot guides your team through modeling, features and existing codebases.

Agent Skills are plain Markdown instructions, one SKILL.md per skill, that an agent loads when a task matches. The SpecsGraph skills teach a connected agent when to read the model, what to ask before it changes anything and how to stage a change the team will accept. They run on the agents you already use: SpecsGraph ships no AI of its own.

Note

Connect the MCP server first

Every skill drives the SpecsGraph MCP server, so connect Claude Code, Cursor, GitHub Copilot or another client before you install them. The skills recognize SpecsGraph by its tools, whatever name you gave the server.

The four skills

Skill	What it does	Ask for it with
`specsgraph-director`	Reads the project state and routes the request to the right specialist. Never writes.	"Let's spec this out", "Where do I start?", "Set up SpecsGraph for this repo"
`specsgraph-engineer`	Domain modeling by interview: subdomains, bounded contexts, the model inside each context, behavior, contracts, glossary terms and roles. The agent proposes, the team ratifies.	"Model this", "Where does the boundary go?", "What invariants does Parcel have?"
`specsgraph-product`	Features, scenarios, roles and terms in plain language. No DDD vocabulary needed.	"Write the scenarios for X", "Spec this feature", "Capture these acceptance criteria"
`specsgraph-brownfield`	Maps an existing codebase into the model one seam at a time, with evidence and a confidence on every proposal.	"Point SpecsGraph at this repo", "What does the current system actually do?"

Each skill works on its own. Most teams install all four and let the director route: it reads the project state, picks the specialist and hands over.

How a skill works

Read. The agent loads the current model for the project and the workstream it is working in, so it starts from what the team agreed.
Agree. It asks one question at a time, each with a recommended answer, and writes nothing until you say yes. Your words become the spec; anything you did not say becomes a question, never a claim.
Stage. Each agreed element goes into an open proposal, one small change at a time.
Review. The agent asks for review. Comments on a node come back as replies in the thread or as a revised proposal.
Approve and publish. A person approves the proposal in the web app, and the approved change is published to your repository. No skill and no MCP tool can approve, and the server refuses an agent that tries. How the spec workflow works follows a change end to end.

Install

Claude Code

The skills ship as a Claude Code plugin. Inside a Claude Code session, add the marketplace and install the plugin:

Text

/plugin marketplace add SpecsGraph/specsgraph-skills
/plugin install specsgraph

Cursor, Codex, GitHub Copilot and other agents

The skills are portable SKILL.md folders that follow the .agents/skills/ convention. From your repository, install them with the skills CLI:

Shell

npx skills add SpecsGraph/specsgraph-skills

Or copy the folders under skills/ in the repository (opens in a new tab) into your agent's skills directory.

Claude.ai

Zip one skill folder from skills/ and upload it under Customize, then Skills. Team and Enterprise owners can provision skills for the whole organization.

Update

Installed with	Update with
Claude Code plugin	`/plugin marketplace update specsgraph`. Third-party marketplaces do not update on their own.
`npx skills add`	`npx skills update`
Claude.ai upload	Zip and upload the changed skill folder again.
Copied folders	Copy them again, or switch to `npx skills add SpecsGraph/specsgraph-skills`.

Releases follow semantic versioning. The changelog in the repository (opens in a new tab) lists what changed in each one.

Example prompts

Prompt	Skill that answers
"Let's spec the parcel dispatch flow."	`specsgraph-director`, which routes to the engineer
"Write the scenarios for parcel tracking."	`specsgraph-product`
"Where does the boundary between Shipping and Notifications go?"	`specsgraph-engineer`
"Point SpecsGraph at this repo and start from the /dispatch endpoint."	`specsgraph-brownfield`

What the skills never do

Approve or publish. Accepting a proposal, resolving a thread and publishing stay with people, and the server enforces it.
Reach anything else. The skills call your SpecsGraph server and, for brownfield work, read the codebase you point them at. They install no software and call no other endpoint.
Hide their instructions. Everything a skill will make your agent do is in its SKILL.md, readable in the repository (opens in a new tab) before you install it.

Next steps

SpecsGraph skills on GitHub (opens in a new tab): the source, changelog and issues.
Working well with agents: the habits the skills build in, for prompts you write yourself.
Start from an existing codebase: what the brownfield skill helps you do, step by step.
MCP tool reference: the tools underneath every skill.