Free SKILL.md scraped from GitHub. Clone the repo or copy the file directly into your Claude Code skills directory.
npx versuz@latest install specgraph-specgraph-skills-specgraph-authoringgit clone https://github.com/specgraph/specgraph.gitcp specgraph/SKILL.MD ~/.claude/skills/specgraph-specgraph-skills-specgraph-authoring/SKILL.md---
name: specgraph-authoring
description: Use when the user wants to author or update a SpecGraph spec — sparking an idea, shaping a problem statement, specifying detail, decomposing into work, or walking a spec to approval. Routes to the right MCP prompt for the current authoring stage.
license: Apache-2.0
metadata:
source: https://github.com/specgraph/specgraph
---
# SpecGraph Authoring
The SpecGraph MCP server delivers full authoring guidance through prompts:
persona, orchestration heuristics, and stage-specific instructions. This
skill is a router. It tells you which MCP prompt to invoke and when. It does
not duplicate the prompt bodies; the server is the source of truth.
## When this skill applies
Trigger on any of:
- The user wants to start a new spec ("let's spec out X")
- The user is mid-funnel and wants to advance ("ready to specify this")
- The user asks for help with an existing spec by slug
- A stage transition just succeeded and the next stage is in scope
## The five-stage funnel
| Stage | Purpose | Output |
|---|---|---|
| `spark` | Take a topic, draft an idea | initial intent + posture |
| `shape` | Refine into a clear problem statement | problem, success criteria |
| `specify` | Add full design detail | constraints, interfaces, risks |
| `decompose` | Break into actionable work | slices, dependencies, edges |
| `approve` | Capture decisions, finalize | decisions + edges + sign-off |
## How to invoke
Each stage has an MCP prompt of the same name. Two equivalent paths:
1. Invoke the MCP prompt directly: `spark`, `shape`, `specify`, `decompose`,
or `approve`. Prompts assemble persona + orchestration + stage content +
current state in one call.
2. Call the `author_start_stage` tool with `stage` and (after spark) `slug`.
Useful when you want the prompt body returned as a tool result for
inspection rather than dispatched as a message.
After the conversation produces a stage output, persist it with the `author`
tool, setting `action` to the stage name (`spark`, `shape`, `specify`,
`decompose`, or `approve`).
## Posture
Three postures govern how much the agent leads:
- **Drive** — short, vague user input. Agent proposes, drafts, runs auto-passes.
- **Partner** — default. Back-and-forth.
- **Support** — long, detailed user input. Agent listens, reflects, drafts on
request.
The composer detects posture from first-turn signals; the user can override
with "switch to drive mode" at any point.
## Conventions
- Slugs are `kebab-case`, derived from intent. The spark stage proposes one;
the user can override.
- Stage transitions are validated server-side. You can't `specify` without a
shape, can't `decompose` without a specify, etc.
- `approve` is the only stage that requires explicit user sign-off. Never
approve on the user's behalf.
## Don't
- Don't invent dotted MCP tool names. SpecGraph tools are flat (e.g., `author`,
not `author.spark`) and use an `action` parameter.
- Don't skip stages. The validation will reject you, and the elicitation is
designed to catch rushed thinking.
- Don't recreate the composer prompts in your own message. Invoke the MCP
prompt and let the server produce the body.
## Reference
Companion skills:
- `specgraph-graph-query` — for "what specs exist," "what's ready," "what
depends on this."
- `specgraph-analytical-passes` — for review passes that run alongside
authoring.
- `specgraph-conventions` — for slug, edge type, and stage transition rules.