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
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
- 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.
- 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. - 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.
- 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.
- 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.
- Build. The task's work items say what to code. The engineer takes one with
work_item_nextandwork_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:
/plugin marketplace add SpecsGraph/specsgraph-skills
/plugin install specsgraphCursor, 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:
npx skills add SpecsGraph/specsgraph-skillsOr 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
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 withwork_item_update, heartbeats, and asks on the item when stuck. - Build status and the roadmap. The engineer and the director read
build_statusandroadmap_getbefore 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:setupwrites the work item section that the web app's Connect an agent panel shows.
Example prompts
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
- 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.