Skip to content

Agent skills

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

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 spec, 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, Claude Code, Codex, Cursor, GitHub Copilot or another client before you install them. The skills recognize SpecsGraph by its tools, whatever name you gave the server.

The five skills

SkillWhat it doesAsk for it with
specsgraph-directorReads 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-engineerDomain modeling by interview: subdomains, bounded contexts and their context map, the model inside each context, behavior, interfaces, terms, roles, decisions and constraints. It also implements agreed work items and reads the build status and the roadmap. The agent proposes, the team ratifies."Model this", "Where does the boundary go?", "What invariants does Parcel have?"
specsgraph-productFeatures, scenarios, roles and terms in plain language, with the use cases that realise each feature. No DDD vocabulary needed."Write the scenarios for X", "Spec this feature", "Capture these acceptance criteria"
specsgraph-brownfieldMaps 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?"
specsgraph-ingestCaptures an existing project from every source it lives in (tracker, code, designs, docs, chat) into one workstream, in phases, and asks every unconfirmed point as a question. Resumable from a ledger on disk."Import our Jira project", "Put everything from Jira, the code and Figma into the spec", "What is still undecided?"

Each skill works on its own. Most teams install all five and let the director route: it reads the project state, picks the specialist and hands over. Questions about what is built or what comes next it answers read only, from the build status and the roadmap.

How a skill works

  1. Read. The agent loads the current spec for the project and the workstream it is working in, so it starts from what the team agreed.
  2. 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. A question for someone who is not in the conversation goes to the workstream with thread_ask.
  3. Stage. Each agreed element is staged as a revision in the workstream's proposal, one small change at a time, grouped into a plan for the task it belongs to.
  4. Review. The agent marks the proposal ready for review. Comments on an artefact come back as replies in the thread or as a revised document.
  5. Accept and publish. A person accepts the revisions into the workstream, submits the task as Ready and publishes it to Main. Publishing is never a skill's act; accepting and Ready are, only with Agent autonomy on.
  6. Build. The task's work items say what to code. The engineer takes one with work_item_next and work_item_claim, codes against the agreed spec and names the item in its pull request; the merge marks the item done. A person marks existing code as implemented and orders the milestones.

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. The skills need the SpecsGraph connector turned on.

Update

Installed withUpdate with
Claude Code plugin/plugin marketplace update specsgraph. Third-party marketplaces do not update on their own.
npx skills addnpx skills update
Claude.ai uploadZip and upload the changed skill folder again.
Copied foldersCopy 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.

What is new in 0.7.0

  • Implementing agreed work. The engineer takes a work item, reads the spec at the item's read.scope, names the item in the pull request, records it with work_item_update, heartbeats, and asks on the item when stuck.
  • Build status and the roadmap. The engineer and the director read build_status and roadmap_get before they answer what is built or what comes next.
  • The 16 kinds. Decisions and constraints, the context map, use case preconditions, use cases on features and scenarios, roles that are external systems, and a bounded context on every new integration event.
  • Brownfield and ingest close by reminding you that a person marks the mapped code as implemented on the Build page.
  • Setup. /specsgraph:setup writes the work item section that the web app's Connect an agent panel shows.

Example prompts

PromptSkill 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
"Import our Jira project, the code and the Figma designs."specsgraph-ingest
"Take the next ready work item and implement it."specsgraph-engineer

What the skills never do

  • Act for people. No skill can publish a task, record a verify or uat result, mark a work item done or edit the work items of a task, mark code as implemented, change the roadmap, or change project, organisation or account settings. Without Agent autonomy, no skill can accept a revision or a plan, choose what a task covers, submit a task as Ready, mark a task done, answer a question, resolve a thread, discard a change, resolve a conflict directly, or complete or abandon a workstream either; the server enforces both.
  • 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