Finding the Skills on Disk

On a Claude Code 2.1.88 or newer install, GSD writes its skills into your per-user Claude configuration directory. On Linux and macOS that lives at ~/.claude/skills/; on Windows it is %USERPROFILE%\.claude\skills\. The GSD installer creates one sub-directory per command, each prefixed with gsd-, and each containing a single SKILL.md file:

~/.claude/skills/
├── gsd-new-project/
│   └── SKILL.md
├── gsd-plan-phase/
│   └── SKILL.md
├── gsd-execute-phase/
│   └── SKILL.md
├── gsd-verify-work/
│   └── SKILL.md
├── gsd-progress/
│   └── SKILL.md
├── gsd-help/
│   └── SKILL.md
└── ... (30+ more)

Go ahead and navigate there now. Run ls ~/.claude/skills/ on your own machine. You should see a long list of gsd-* directories plus any other skills Claude Code has picked up from other tools or from your own hand-authored experiments. This is not a sandbox — it is your real home directory, and those markdown files are the exact instructions Claude reads when you invoke a GSD command.

The SKILL.md Format

Every skill file Claude Code 2.1.88 and later consumes follows the same shape: a YAML frontmatter block, a heading, and an instruction body. The frontmatter carries two required keys — name and description — and the body is markdown prose that becomes the instruction set the model sees when the skill activates.

Here is the minimum viable skill file:

---
name: gsd-progress
description: "Show GSD project progress and current phase status"
---
# GSD Progress Report

When the user asks about the current state of the project, read
`.planning/STATE.md` and `.planning/ROADMAP.md`. Produce a compact
summary containing:

1. The current milestone (from ROADMAP.md).
2. The active phase (from STATE.md).
3. The most recent three completed work items.
4. Any open blockers recorded under the "Blockers" heading.

Render the output as a markdown table with two columns: "Item" and
"Status". Do not fabricate phase data --- if STATE.md is missing, say
so and suggest running `/gsd:new-project` to initialize it.

That is a complete, working skill. Drop that file into ~/.claude/skills/gsd-progress/SKILL.md, reopen Claude Code, and typing “show me the GSD progress” will surface it as a candidate skill. The name field is the stable identifier — it also determines the slash-command alias (/gsd:progress maps to gsd-progress) on runtimes that expose slash commands. The description field is where the real magic lives, and it deserves its own section.

How Trigger Descriptions Work

Claude Code does not load every skill on disk into every request. That would blow the context window inside of a dozen commands. Instead the runtime keeps a lightweight manifest of all installed skills — just their names and descriptions — and when a new user message arrives, it pattern matches the message against those descriptions to decide which skills to promote into the full context. Only promoted skills have their instruction body loaded.

The description is therefore the activation contract. A vague description like "Help with GSD" will match almost everything and almost nothing usefully. A concrete one like "Show GSD project progress and current phase status" will match phrases like “where are we on the project”, “what phase are we in”, or “give me a status update” without swamping unrelated requests.

When you author your own GSD-adjacent skills, invest time in the description line. Use action verbs, name the artifact you operate on, and include a few of the phrasings users actually say out loud. A good description is not a summary of what the skill does — it is a list of triggers that should fire it.

The Installer’s Role

GSD ships as an npm package. When you run npx gsd-build install, the installer does three things in sequence:

1. Detect the runtime. It looks at which agent CLIs are installed on the current machine — Claude Code, Codex, Cursor, Windsurf, and so on — and also at the version of Claude Code it finds. The 2.1.88 cutoff matters: earlier versions do not understand the skills directory layout at all.

2. Read its source skill definitions. GSD carries its command definitions in a single canonical form inside the npm package. These are the master copies.

3. Transform and write. For each detected runtime, the installer rewrites the master skill into whatever format that runtime actually consumes, then drops the result into the right directory. One master, many derivatives.

This architecture is why the same /gsd:plan-phase command behaves identically whether you are driving Claude Code, Codex, or Cursor — the installer is doing the translation work up front so the user-facing surface is uniform.

Skills versus Legacy Slash Commands

Before Claude Code 2.1.88, Claude Code had no notion of skills. The only way to ship reusable instructions was as a slash command: a markdown file living at ~/.claude/commands/gsd/[name].md that the user invoked by literally typing its name. There was no description field, no trigger matching, no auto-activation — the user had to know the command existed and type it explicitly.

GSD still supports this old world. If the installer detects a pre-2.1.88 Claude Code install, it writes legacy slash commands instead of skills:

~/.claude/commands/gsd/
├── new-project.md
├── plan-phase.md
├── execute-phase.md
├── verify-work.md
└── ...

You interact with both layouts the same way from the user side — /gsd:plan-phase works whether it resolves to a skill or a legacy command — but under the hood the runtime treats them differently. Skills are auto-activating and context-aware; legacy commands only fire on an explicit invocation. If you upgrade Claude Code from an older version, run npx gsd-build install again and the installer will migrate you forward automatically, leaving the legacy directory in place so nothing breaks mid-session.

What You Can Do With This Knowledge

Once you internalize that GSD skills are just markdown on disk, a long list of previously scary tasks becomes trivial. You can diff two installs to see what changed between GSD releases. You can keep a local patch directory and re-apply your own edits after an upgrade. You can fork a skill, rename it to gsd-plan-phase-health, tailor it to your domain, and have both the generic and the specialized version coexist in the same directory. You can hand-write skills that call GSD primitives without waiting for upstream to ship them. Everything is text, everything is readable, and nothing is hidden.

The rest of this part walks through each of those capabilities in detail, starting with the compatibility matrix that determines where your skills actually land.

The Compatibility Matrix

The table below lists every runtime the GSD installer currently supports, the format it emits for that runtime, the directory where the output lands, and the command you can run to confirm the install succeeded.

Twelve runtimes, twelve directory layouts. Four of them (Claude Code 2.1.88 and later, Codex, Cursor, and Qwen Code) converge on the same skills-with- SKILL.md shape, which is the format this book treats as canonical. The other eight each require the installer to do some amount of translation work, and understanding those translations is the key to debugging any cross-runtime weirdness you run into.

How the Installer Transforms

The installer maintains a single internal representation for each GSD command — call it the “source form.” When a runtime requires a different format, the installer applies a translation pass. Here are the three most important translations.

Runtime-Specific Gotchas

Even when you know the translation rules, a few runtimes have quirks worth calling out explicitly.

Non-Claude Model Profiles

Most GSD subagents (the executor, planner, researcher, and verifier roles) are built on Claude Code’s subagent spawn primitive, which defaults to whichever Anthropic model the parent session is running. That is usually what you want — consistency across the session — but it is a footgun the first time you run GSD inside an OpenRouter-fronted Claude Code or on a locally hosted model.

The problem: even when the parent session is routed through OpenRouter, a spawned subagent may try to call Anthropic directly unless you explicitly tell it not to. You end up paying OpenRouter for the parent and Anthropic for every subagent spawn simultaneously.

GSD ships an inherit profile for exactly this case. When you select the inherit profile (via /gsd:set-profile inherit or by editing .planning/config.json), every spawned subagent will reuse the parent session’s model configuration instead of defaulting to Anthropic. If the parent is on OpenRouter, the subagents are on OpenRouter. If the parent is on a local Ollama model, the subagents are too.

Verifying an Install

Regardless of runtime, the fastest way to confirm GSD is actually installed is to run the /gsd:help command (or its runtime-specific equivalent from the matrix). It is a skill like any other, and if it responds with the GSD command listing, everything else is wired up correctly. If it does not respond, the first diagnostic step is to ls the install directory for your runtime and confirm the gsd-* entries exist. Ninety percent of install problems are really “I am on a runtime I did not expect to be on” problems, and the matrix is there to cut that debugging time down to seconds.

The Concept

When GSD spawns a subagent — an executor running a phase, a planner drafting the next set of work items, or a researcher collecting domain information — it builds the subagent’s system prompt from a stack of pieces: the subagent’s role definition, the current project state, the task at hand, and optionally, one or more injected skill blocks drawn from local project directories.

Those injected blocks arrive in the subagent’s prompt as an <agent_skills> section. From the subagent’s point of view, they are just more instructions — indistinguishable from the built-in role definition except that they came from a project-local directory rather than from the GSD source tree. This is pure prompt augmentation. There is no plugin system, no sandbox, no new execution path. The injected content simply becomes part of what the subagent sees.

That simplicity is the feature. You can teach a GSD researcher about FDA endpoints the same way you would teach a human researcher about them: by handing over a short written brief. The researcher reads the brief, integrates it into its working knowledge, and uses it for the duration of the task.

Configuration Syntax

agent_skills is configured in the project’s .planning/config.json file. The key is agent_skills, and its value is an object mapping subagent type names to arrays of directory paths. Each path is resolved relative to the project root.

{
  "agent_skills": {
    "executor": ["./skills/domain-knowledge/"],
    "planner": ["./skills/planning-rules/"],
    "researcher": ["./skills/research-sources/"]
  }
}

When a subagent of a given type spawns, the installer walks the directories listed under that type, reads every .md file it finds, concatenates the contents, and wraps the result in an <agent_skills> block inside the subagent’s prompt. Files are read in lexicographic order, so prefixing names with 01-, 02-, and so on gives you explicit control over the final ordering when order matters.

Which Agent Types Accept Skills

Not every subagent type honors agent_skills. As of the current release the supported types are:

• executor — the phase-running worker. Injected skills here shape how code gets written, which conventions get followed, and which libraries get preferred. Good for “our codebase uses X pattern” style rules.

• planner — the task decomposition agent. Injected skills here shape how phases get broken into work items and what kinds of safety rails the planner enforces. Good for “never do X without Y” style rules.

• researcher — the information-gathering agent. Injected skills here shape which sources get consulted and what domain vocabulary gets used in the resulting RESEARCH.md. Good for teaching the researcher about APIs, standards, databases, and terminology it would not otherwise know.

The verifier, documenter, and other specialized subagent types currently use a fixed instruction set and do not read agent_skills. That may change in a future release; for now, if you need to customize verification behavior, you do it by editing the global skill file directly.

Writing a Skill Directory

A skill directory is just a directory. Create it anywhere under your project root (convention is ./skills/[name]/), drop one or more .md files in it, and list the directory in agent_skills. That is the whole contract.

The markdown files inside do not need frontmatter. They do not need a name or description field. They just need to contain the instructions you want the subagent to read. You can write them in whatever style feels natural — prose, bullet lists, labeled sections, annotated code examples — and the subagent will parse them the same way it parses any other instruction block.

The reason naming is descriptive (rather than formal) is that every .md file’s content gets concatenated together at spawn time. The subagent does not see file boundaries; it sees one long block of text. File names serve only two purposes: ordering (lexicographic) and readability for you when you come back to the directory in six months.

How Injection Affects Behavior

The injected <agent_skills> block lives inside the subagent’s prompt for the entire duration of its task. That means:

• The instructions persist across every tool call the subagent makes. A researcher that spawns a web search, then a file read, then another web search still has the FDA brief visible through all three calls.

• The instructions are visible to the model at every decision point. When the model is picking which URL to fetch or which section to write first, it is weighing those choices against the injected skill content.

• The instructions do not persist beyond the task. Once the subagent exits, the injected block goes with it. The next subagent spawn rebuilds the prompt from scratch, picking up any edits you made to the skill files in between.

That last point is important: you can edit a skill file mid-session and the next subagent spawn picks up the change immediately. There is no rebuild step, no cache to invalidate, no installer to re-run.

A Minimal Example

Suppose you are building a product that must never merge to main without first running an integration test. You want the GSD planner to refuse to generate a plan that skips this step. Here is the full contents of ./skills/planning-rules/no-untested-merges.md:

# Merge Safety Rule

Never produce a plan whose final step is a merge to `main`, `master`,
or any protected branch unless the plan also contains an explicit
integration test step that runs BEFORE the merge and must pass.

If a user asks for a plan that would merge without testing, respond
with a plan that adds the missing test step and a one-line note
explaining why.

Applies to: all merge-containing phases, all branches matching
`main`, `master`, `release/*`, or `prod`.

Six lines of instruction. That is enough. With this file in place and planner pointing at ./skills/planning-rules/ in agent_skills, every subsequent /gsd:plan-phase invocation in this project will generate plans that include a test step before any merge, and will add a short justification when the user’s request would have skipped one.

The planner did not need to be recompiled. The GSD installer did not need to be rerun. You wrote six lines of markdown, saved the file, and the next planner spawn behaved differently. That is the entire feature.

When to Reach for This Tool

agent_skills is the right tool whenever your customization need has three properties: it is specific to one project, it is worth writing down, and it would benefit from being seen by a particular subagent role on every spawn. Domain vocabulary, compliance rules, in-house API conventions, preferred libraries, house coding standards, data-handling constraints — all of these fit naturally.

It is the wrong tool for global rules (those belong in a hand-authored global skill), for one-off asks (those belong in the prompt itself), and for rules the whole team has not yet agreed on (those belong in a discussion, not a config file). Within its sweet spot, though, it is the single most powerful lever GSD gives you for shaping subagent behavior — and the next chapter walks through a complete, end-to-end use of it.

What MCP Actually Is

MCP — the Model Context Protocol — is an open standard, published by Anthropic, for connecting AI assistants to external tools and data sources. At its heart it is a small, stable JSON-RPC interface. A program that implements MCP is called an MCP server. A program that connects to one is called an MCP client. Claude Code is a client. Almost everything else in this chapter is a server.

Each MCP server exposes a handful of tools. A tool has a name, a JSON schema describing its arguments, and a function that runs when Claude Code invokes it. During a conversation, Claude Code sends a list-tools request to every connected server at startup, merges the results into its own tool surface, and from that point on, calling an MCP tool looks identical to calling a built-in one. The assistant does not know or care whether read_file is implemented in Claude Code itself or served by a filesystem MCP running on your laptop.

This is a much bigger deal than it sounds. Before MCP, every integration between an assistant and an outside service had to be hand-coded, vendor by vendor, with a bespoke protocol each time. MCP collapses that sprawl into one JSON-RPC shape that anyone can implement in a weekend. You write the server once, and every MCP-aware client — Claude Code, Claude Desktop, the various editor plugins — can use it without modification.

Why MCP Matters for GSD Specifically

Here is the part that surprises people: you don’t have to tell GSD anything about your MCP servers. It figures them out on its own.

As of GSD v1.30 (see CHANGELOG entry #1603), the executor and planner subagents are explicitly instructed, in their system prompts, to inspect the current set of available tools before drafting a plan or executing a task, and to use any MCP tools they find as if they were first-class capabilities. That was a one-line change to the subagent prompt templates and it unlocked an enormous amount of behavior. If you connect a Postgres MCP server to Claude Code, the planner now sees postgres.query in its tool list and will naturally reach for it when you ask it to plan a database migration. If you connect Google Stitch’s MCP, the planner sees stitch.generate_screen_from_text and will write plan steps that call it directly.

You don’t edit a GSD config file to declare the tool. You don’t hand-wire anything in .planning/. The subagents inherit Claude Code’s entire tool surface, MCP and all, and they use what they find.

Transport Types: stdio and HTTP

MCP servers come in two flavors, distinguished by how the client talks to them.

How Discovery Works

When Claude Code starts a session, it walks a short, ordered list of configuration sources and merges the results. The project-scoped file .mcp.json in the current working directory comes first; the user-scoped file ~/.claude.json comes second. A server name defined in the project file takes precedence over the same name in the user file, which means you can ship a project-local override for a server that you otherwise use everywhere.

For each server entry, Claude Code either launches a subprocess (stdio) or opens a connection (HTTP), sends the MCP handshake, and asks for the server’s tool listing. Those tools are added to the set of things the assistant can invoke in the current conversation. GSD’s subagents, when they are spawned by commands like /gsd:plan-phase or /gsd:execute-phase, inherit the same tool surface from the parent Claude Code process. There is no second discovery step, no second config file, no second place for things to go wrong.

The upshot is that an MCP server you add once is immediately available everywhere GSD does useful work: planning, execution, verification, review. The subagents don’t need to be taught about the new tool. They just find it sitting on the shelf.

A Short History and Why It Matters

MCP is young. The specification was first published in late 2024, the reference implementations appeared shortly after, and the ecosystem of third-party servers has been expanding roughly monthly since then. In practical terms this means three things. First, the protocol surface is still small enough to read in an afternoon — if you’re curious about what an MCP message looks like on the wire, the spec is not yet so sprawling that you need a guide to navigate it. Second, new servers are appearing constantly, and the server you want probably exists (or will exist by next month) even if it doesn’t show up on the first page of search results today. Third, the protocol is versioned and backwards-compatible in a way that means the config patterns in this guide are unlikely to break under you in the near term — when the spec evolves, it does so by adding new capabilities to the negotiation step rather than breaking old message shapes.

The reason any of this matters for a GSD user is that the protocol’s youth shows up in rough edges. Error messages from MCP servers are sometimes less polished than the equivalent error from a mature vendor SDK; documentation for less-common servers is sometimes scattered across a README, a changelog, and one Discord thread; and the first time you wire up a new server, expect to spend ten minutes figuring out which environment variable the server’s author chose to name the API key. None of this is fatal. All of it is the cost of being a year early. The payoff is that the glue code you write today will still work in three years, because the protocol itself is designed to outlive any one vendor’s implementation.

What MCP Is Not

A brief list of things MCP is not, because misconceptions in this space are expensive.

MCP is not a replacement for HTTP APIs. If you have a REST API that you love and that works, MCP does not make it faster or better; it wraps it. The value of MCP is not performance. It is standardization. An MCP server in front of your REST API means any MCP-aware client can use it without hand-coding the integration. That’s worth something if you have more than one client. It’s worth less if you only ever use one.

MCP is not an agent framework. The protocol says nothing about how the assistant decides which tool to call, how to chain tool calls together, how to handle errors, or how to plan multi-step work. That’s the assistant’s job. MCP just moves bytes between a client and a server. The intelligence lives on either side of the wire, not in the wire itself.

MCP is not a permissions system. Giving a tool to Claude Code via an MCP server grants the assistant whatever access the underlying credentials provide. If your Postgres MCP server connects with a superuser account, Claude Code gets superuser access to the database, and so does every subagent GSD spawns. Scope your credentials at the database, filesystem, or API level — that’s where permissions belong — and treat MCP as a transport layer that will faithfully carry whatever authority you give it.

MCP is not magic. The tools you install are the tools you get. If no one has written an MCP server for the thing you want to integrate with, you have two options: find a close-enough existing server (a generic HTTP fetch server, a shell-command runner, a scripting server) or write one yourself. Writing one yourself is surprisingly cheap — the reference TypeScript and Python SDKs make a minimum-viable server about fifty lines of code — but it is still work, and no amount of AI enthusiasm will conjure a server that doesn’t exist yet.

Adding Servers via the CLI

The claude mcp add command is the fastest way to register a server without hand-editing JSON. Two examples cover the two transports:

# Register a local stdio server (the Stitch proxy, which we'll meet
# in Chapter 7). The "--" separator marks the end of claude's own
# flags and the start of the subprocess command line.
claude mcp add stitch --transport stdio -- npx @_davideast/stitch-mcp proxy

# Register a remote HTTP server at user scope (-s user means every
# project on this machine will see it).
claude mcp add my-api --transport http https://api.example.com/mcp -s user

The CLI writes the entry to the appropriate config file for you — project or user scope, depending on the -s flag — and from that point on, the server is indistinguishable from one you added by editing JSON directly. Use the CLI for one-shot experimentation; use JSON files when you want to commit the config alongside the rest of your project or when you want finer control over env-var injection.

Project-Scoped Configuration: .mcp.json

A .mcp.json file in the root of your project declares servers that are specific to this project and nowhere else. The shape is dead simple:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    }
  }
}

The top-level mcpServers object holds one entry per server, keyed by a short name of your choosing (this name becomes the prefix on tool calls — so filesystem.read_file would be the fully qualified tool name in the above example). The command is the binary to launch, and args is the argv passed to it. That’s the minimum viable config.

User-Scoped Configuration: ~/.claude.json

The user-scoped file lives at ~/.claude.json and has the same shape, just in a different place. Entries here apply to every project you open in Claude Code, unless a project-local entry with the same server name overrides it. Use the user-scope file for personal utilities: your filesystem server pointing at ~/projects, your GitHub server with your personal access token, whatever daily-driver search MCP you’ve settled on.

Project vs User Scope: How to Decide

The rule of thumb is simple. If the tool is specific to this codebase — a database server configured with this app’s connection string, a Stitch project that holds this app’s UI, a staging API endpoint you only ever hit from this repo — use project scope. If the tool is a personal utility that you’d want in every session — filesystem, GitHub, your search engine of choice — use user scope. When in doubt, start at user scope and move it down to project scope only if it turns out to need project-specific credentials or paths.

A slightly more nuanced version of the same rule: ask yourself what would happen if a teammate cloned your repo and ran Claude Code in it. Would they need this server to reproduce your work? If yes — the database MCP, the Stitch MCP pointing at a shared project, the deployment API wrapper — it belongs in project scope, committed (minus credentials) so the next developer gets it for free. If no — your personal filesystem server, a search MCP pointing at your own notes, a weather server you installed for fun — it belongs in user scope where it stays with you and doesn’t clutter the shared config. The tiebreaker, when both feel true, is whether the tool holds state that is specific to this project. A Postgres MCP holding this app’s connection string clearly does. A GitHub MCP holding your personal access token clearly does not, even if you only ever use it in one repo at a time.

There’s a third scope worth knowing about, even though most users will never touch it directly: the session-local scope created by claude mcp add without either -s project or -s user. This adds a server for the duration of the current Claude Code session only, in-memory, with no file changes. It is useful for truly one-shot experiments — you want to poke at a new server for ten minutes without committing to it — and it vanishes when you exit the session. Treat it as a try-before-you-buy mode.

Environment Variables in Config

Hardcoding an API key into .mcp.json is a loaded gun. Even if you never commit the file, it still sits on your disk in plaintext, readable by any process running as your user, and any casual cat .mcp.json will print it to a terminal that might be scrolled back or screen-shared or logged by an operator tool. The correct pattern is env-var interpolation: store the secret in your shell environment and reference it by name in the config.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

The env block passes environment variables into the subprocess. Values of the form ${NAME} are expanded from your own environment at the moment Claude Code spawns the server — so the real token lives in your shell profile (or a secrets manager, or a dotenv file that is itself gitignored), not in the config file. If the variable is unset, the substitution leaves an empty string and the server will almost always fail with an auth error; that’s the correct failure mode.

One more footgun worth flagging: some editors and IDEs offer to “helpfully” open .mcp.json in a JSON schema view that pings a remote schema registry. Disable this for any config file that contains internal endpoint URLs or server names you’d rather not publish to someone else’s telemetry. The GSD guide team has seen this happen once. Once is enough.

Combining Agent Skills with MCP

Part I of this guide introduced agent skills — the small project- scoped prompt fragments that get injected into a subagent’s context whenever it runs in this project. Skills and MCP tools compose in a way that is more powerful than either one alone.

The trick is that a skill can refer to an MCP tool by name. A skill is just prose injected into the planner’s or executor’s prompt, and if that prose says “when planning database migrations, always call postgres.query first to inspect existing tables,” the planner will do exactly that. The skill doesn’t need to know how postgres.query works; it just needs to mention the name. The MCP server already told Claude Code about the tool’s schema during discovery, so the planner can fill in the arguments correctly on its own.

This pattern is how you bake team conventions into a project. Your team decides that every new feature needs a database schema check before planning? Write a one-paragraph skill that says so, mention the postgres.query tool by name, and every subsequent /gsd:plan-phase run will follow the rule without anyone having to remember to invoke it. The same trick works for any MCP server: a skill that says “for any UI task, always call stitch.list_projects first to confirm the Stitch project exists” costs you a paragraph and saves you a class of “undefined project” errors you would otherwise hit at execute time.

A worked example makes this concrete. Suppose your team has agreed that every database-touching phase must start by reading the current schema, and every UI-touching phase must start by confirming the Stitch project exists and has the expected screen count. You can bake both rules into a skill like this (placed in .claude/skills/team-conventions.md or wherever your project’s agent skills live):

# Team conventions for planning and execution

## Before any database migration task
1. Call postgres.query with a schema inspection query
   against information_schema.tables and information_schema.columns
   for the affected tables.
2. Include the returned column list in the task preconditions.
3. Only then draft the migration SQL.

## Before any Stitch-generated UI task
1. Call stitch.list_projects and confirm the configured project
   ID is present.
2. Call stitch.list_screens for that project and record the
   current screen count.
3. If the screen count differs from what DISCUSS.md claims, stop
   and surface the mismatch instead of generating blindly.

The skill is maybe thirty lines of prose. The behavior change is substantial: you stop finding out about schema drift at execute time and start finding out about it at plan time, when fixing it is cheap. Notice that this pattern does not require any changes to GSD’s source code, to the MCP servers themselves, or to Claude Code’s configuration. It is entirely text, and the text flows through the same discovery-and-injection paths you already use for every other skill.

The reason this works is worth pausing on. Subagent prompts are assembled fresh at the start of each subagent invocation: the base template, the current phase’s context, any applicable skills, and the current tool manifest. When a skill mentions a tool name, the planner sees that mention and the tool’s schema side by side. It doesn’t have to guess what arguments the tool takes, because the schema is right there. It doesn’t have to be reminded to use the tool, because the skill says so in plain language. Skills and MCP compose cleanly because they’re both contributing to the same assembled prompt from different directions.

The GSD Plugin Format (Issue #1883)

There’s a larger integration idea in the pipeline. GSD issue #1883 tracks a plan to package GSD itself as a Claude Code plugin — a single installable unit that would bundle GSD’s skills, subagent templates, and a dedicated MCP server, all in one place. The promise is that a user could run one install command and get the entire GSD experience, with its own MCP surface exposed as a first- class tool set, rather than having GSD live alongside MCP as a separate concern.

This is on the roadmap for v1.32 or later — the plugin format is still evolving, and the schema the plugin manifest will use is not yet fixed. Committing to a specific shape in this guide would be premature. The thing to know is that it’s coming, that it is specifically designed to make MCP integration a first-class part of GSD rather than an afterthought, and that the scenarios in this part will still work on the plugin version because the underlying primitives are unchanged. Follow the issue if you want early visibility.

Failure Modes: When an MCP Server is Unavailable

An MCP server can fail mid-execution. The subprocess crashes, the remote endpoint returns a 500, the network is flaky, the auth token expires at exactly the wrong moment. What happens then?

Claude Code returns a tool error to the agent that made the call. The error is not silent: it propagates back as a failed tool response with an error message attached. GSD’s executor subagent sees the error and does one of two things.

The first option is a retry, chosen when the failure looks transient — a network timeout, a 503, an obviously flaky response. The executor will retry the same tool call, sometimes with a short delay, before concluding that the problem is real. This handles most of the everyday flakiness you encounter with remote servers.

The second option is to mark the task as blocked and write a deviation note to the execution log. A deviation note is the executor’s way of saying “I can’t finish this task and the reason is not my fault.” It includes the original plan step, the tool error, and enough context for a human to resume work later. The phase does not silently complete; it ends in a blocked state, and the status command (/gsd:status or similar) will surface the blockage the next time you ask.

The plan does not degrade silently. Failed MCP calls are visible in the executor log, deviation notes make them unmissable, and the phase-completion gate refuses to pass a phase where execution was blocked on a tool error. If you’ve been running GSD long enough to trust it, this is the behavior you want — the tool doesn’t lie about what happened, it tells you something broke and stops.

Observability: Knowing What Your MCP Servers Did

An underappreciated part of running MCP at scale is knowing what your servers have actually been doing. Claude Code’s conversation log shows you every tool call the assistant made, but once you have five or six MCP servers running, that log can get noisy, and correlating “this file on disk” with “this tool call that produced it” is not always easy from the transcript alone.

Three patterns help. First, most MCP servers can be started in a verbose or debug mode that prints each tool invocation to stderr. Claude Code surfaces server stderr in its own logs, so turning on verbose mode on a suspect server is often the fastest way to catch a misbehaving call. The flag is server-specific (look for –verbose, –log-level debug, or an environment variable like LOG_LEVEL=debug), but it exists almost everywhere because MCP server authors are themselves debugging their own servers against Claude Code and need the same signal.

Second, for servers you write or control, emit a one-line audit record per tool call: timestamp, tool name, argument summary, outcome, duration. Pipe it to a file or to your logging pipeline. When something goes sideways at execute time, the audit log tells you what actually happened versus what the plan says was supposed to happen — and those two narratives are not always the same.

Third, for production-grade setups, consider wrapping your MCP servers behind a single reverse-proxy MCP that logs all traffic and then forwards calls to the appropriate underlying server. This adds a hop but gives you one place to look for everything. It’s overkill for personal projects and exactly right for shared team infrastructure where “who called what, when, against which database” is a compliance question with an actual answer.

Version Drift: What Happens When a Server Changes

Your MCP servers will change under you. The Stitch proxy will publish a new version that renames a tool argument. The Postgres server will add a new capability you’ve been wanting. A third-party server you depend on will be deprecated in favor of a successor that is almost but not quite backwards-compatible. None of this is exotic; it’s normal package ecosystem behavior, and MCP is no different from npm or pip in that regard.

GSD copes with this better than you might expect, because the discovery step happens at the start of every session. The planner sees the current set of tools with the current schemas — not a cached snapshot from when you first configured the server. If a tool’s argument list changes overnight, the next plan-phase run will use the new shape without you having to update anything in GSD. If a tool disappears entirely, the planner will stop proposing it, because it won’t see it.

The failure mode to watch for is a skill that names a tool explicitly. If your team-conventions skill says “always call postgres.query” and someone upgrades the Postgres MCP to a version where that tool was renamed to postgres.execute, the skill will keep asking for the old name, the planner will try to call it, and the call will fail. The fix is to update the skill to match. A short CI check that grep-s your skills for known MCP tool names and cross-references them against a list of currently- installed servers is cheap and will save you a debug session.

The overarching theme of Part II is that MCP is plumbing, and good plumbing disappears. Once your servers are configured, the gitignore is in place, and the env vars are exported, you stop thinking about MCP at all. GSD’s planner writes plans that use the tools you’ve plugged in, the executor calls them, and the outputs land on disk. The configuration work is upfront and small. The payoff is that every subsequent plan and every subsequent execution has access to the real state of your project — the real schema, the real Stitch project, the real repository — and the quality of the resulting work rises accordingly. That is the entire argument for connecting GSD to MCP, and it is the reason Part III will assume all of this is in place when it turns to multi-repo and monorepo workflows.

The Problem: Shared Planning State

The default assumption baked into GSD is that a repository has one active plan at a time. The files in .planning/ — STATE.md, ROADMAP.md, REQUIREMENTS.md, the phase directories — describe a single timeline of intent. Commands like /gsd:progress and /gsd:next read that timeline to decide what to tell you. /gsd:execute-phase writes to it.

If you try to run two unrelated workstreams against that shared state at the same time, bad things happen. STATE.md flips between them as each track edits it. The phase numbering collides. /gsd:progress reports “phase 4 in progress” when you meant that for the backend feature, and the frontend lead reads it and wonders why their redesign lost two phases overnight. The ROADMAP gets clobbered because the last writer wins. Every single one of those symptoms traces back to the same root cause: two independent timelines trying to share one set of planning files.

Workstreams and workspaces both solve that root cause. They solve it at different layers of the stack, and they have different costs.

Workstreams: One Repo, Many Timelines

Workstreams were introduced in GSD v1.28. The idea is dead simple: if you already have one repo, keep one repo, but give each independent timeline its own isolated planning subtree. Under the hood, a workstream is a directory under .planning/workstreams/ that contains its own STATE.md, ROADMAP.md, REQUIREMENTS.md, and phase directories — a complete parallel planning tree, scoped under a name of your choice. When you switch to a workstream, GSD transparently re-roots all its planning operations to read and write from that subtree. The root .planning/ is untouched.

The commands are short and predictable. /gsd:workstreams create <name> creates a new one. /gsd:workstreams switch <name> makes it the active workstream for subsequent commands. /gsd:workstreams list shows all of them. /gsd:workstreams complete <name> archives one when its feature ships. The switch itself is essentially free — GSD just updates a pointer to the active workstream directory — so you can flip between two or three of them many times a day without thinking about the cost.

What workstreams don’t do is give you git isolation. The code is still the same checkout. If two workstreams both want to edit src/billing.ts on the same branch, they will conflict in the same way they would without workstreams. Workstreams isolate planning state, not source state. For many real projects that distinction is exactly right, because the planning collision is the painful one and the source collision is already handled by git.

Workspaces: Many Repos, One Plan

Workspaces are the heavier instrument, also introduced in v1.28. A workspace is a separate directory — by convention under ~/gsd-workspaces/<name>/ — that contains one or more named repositories, each checked out as either a git worktree or a full clone, plus a workspace-level manifest file called WORKSPACE.md. Each repo inside the workspace has its own independent .planning/ subtree. The workspace itself is the coordination layer: it knows which repos are in the workspace, tracks cross-repo status in its manifest, and lets you run coordinated planning without having to merge the repos into a monorepo you didn’t want.

The commands mirror the workstream ones but operate at the repo-set level. /gsd:new-workspace –name v2-launch –repos api,web-frontend,admin-dashboard creates a workspace named v2-launch containing three repos. /gsd:list-workspaces shows all configured workspaces. /gsd:remove-workspace v2-launch tears one down when it’s done. The –strategy flag takes one of two values:

• worktree (the default) creates a git worktree of each named repo. Worktrees share object storage with the parent checkout, so they’re cheap to create and cheap to keep around. The trade-off is that you can’t have two worktrees on the same branch of the same repo at the same time — git refuses.

• clone performs a full git clone of each named repo into the workspace directory. This is slower and uses more disk, but it gives you complete isolation — the workspace’s copy of each repo is genuinely independent from your main checkout and can sit on any branch without conflict.

Workspaces cost more to create than workstreams because they involve actual git operations — worktree creation or cloning — and a new directory tree on disk. A workspace with three repos takes a few seconds to materialize, not the sub-millisecond switch of a workstream. That’s the right cost when you actually need repo-level isolation, and the wrong cost when you don’t.

Decision Table

The shortest path to the right answer is to ask: do my parallel timelines share code, or do they share planning? If they share code, a workstream is what you want. If they need different code or different git state, a workspace is what you want.

One More Consideration: How Long Does the Work Live?

A secondary question worth asking before you pick is how long the timeline is expected to live. Workstreams are well suited to long-lived, repeating tracks: “the backend team’s current feature”, “the ongoing observability migration”, “this quarter’s performance work”. They rotate through many features over their lifetime, and the fact that their STATE.md persists across those features is useful.

Workspaces are better suited to cohorts of work that share a release — the kind of thing where you’d otherwise say “we’re shipping v2 across three services and I need to track all three together”. When the cohort ships, you remove the workspace. The repos themselves live on, but the workspace’s WORKSPACE.md and its coordination state get archived or deleted along with the launch it tracked.

Neither pattern is wrong for the other’s use case, but using a workstream for a launch cohort tends to feel fiddly (you end up making a workstream in each repo and hand-coordinating) and using a workspace for a long-lived single-repo track tends to feel heavy (you end up with a workspace directory that never quite gets cleaned up). Match the lifetime of the construct to the lifetime of the work.

What workflow.use_worktrees: true Does

In .planning/config.json, a workflow setting controls how parallel execution is sequenced:

{
  "workflow": {
    "use_worktrees": true,
    "cleanup_worktrees": true
  }
}

When use_worktrees is true, /gsd:execute-phase creates a temporary git worktree for each parallel executor agent it spawns. Each agent gets its own private filesystem view of the same git history, rooted at a scratch directory under .planning/worktrees/ (or wherever the config points). The agents do their work inside those scratch directories, and once the phase completes, the orchestrator walks the set and aggregates their results. If cleanup_worktrees is also true, the scratch directories are removed after aggregation.

Without worktrees, parallel executors would share the main checkout. That’s not a theoretical problem — it’s a concrete, reproducible one. Two agents editing the same file race. Two agents staging different versions of a change overwrite each other. A half-applied refactor gets committed on top of an unrelated agent’s fix and the git history becomes unreadable. Worktrees solve this by giving each agent a filesystem it doesn’t have to share with anyone else, while still keeping all of them rooted in the same git repository so the orchestrator can collect their output.

The STATE.md Ownership Rule

This is the critical constraint. Get it right, and parallel execution is safe. Get it wrong, and you reintroduce the lost-update bug that Issue #1571 was filed to fix.

The rule is small enough to state in one sentence: only the orchestrator writes to STATE.md or ROADMAP.md. Everything else in the design follows from that constraint.

What Agents Actually Write: SUMMARY.md

Each parallel executor agent writes exactly one file in its worktree that is visible to the rest of the system: a plan-local SUMMARY.md. The SUMMARY.md format is intentionally small and additive. It captures:

• what the agent was asked to do (copied from its slice of the plan),

• what it actually did (files touched, tests run, tests passing),

• what it didn’t do and why (blocking dependency, unclear requirement, environmental failure),

• any deviations from the plan that need to be reconciled at aggregation time.

The SUMMARY.md is written in the worktree, not in the main checkout. It lives next to the agent’s work, and it describes what that agent did within its own sandbox. The orchestrator is responsible for reading it and deciding what to do about it. The agent never tries to speak on behalf of the plan as a whole, and the agent never writes into STATE.md or ROADMAP.md in the main checkout or in its own worktree. If you find yourself writing an executor that edits STATE.md, stop. You are reintroducing #1571.

Post-Wave Aggregation

After all parallel executors in a wave finish, the orchestrator runs an aggregation step. It:

1. Enumerates the worktrees created for this wave.

2. Reads each worktree’s SUMMARY.md.

3. Reconciles the set against the master plan — which slices completed, which slices deviated, which slices blocked.

4. Updates STATE.md and ROADMAP.md in the main checkout with the aggregated result. This is the single write to the shared planning state for the entire wave.

5. If cleanup_worktrees is true, removes the worktrees and prunes the git worktree registry.

The important property is that STATE.md goes from pre-wave to post-wave in exactly one transition, authored by one process (the orchestrator), reflecting the aggregate of what all the executors did. There is never a window where two writers are touching STATE.md at the same time, because there is only ever one writer.

The git clean Prohibition

The prohibition applies to any variant of the command — git clean -f, git clean -fd, git clean -fdx — and the wrapper will reject the call with a diagnostic that explains why. If you have a legitimate need to remove large quantities of untracked files from a worktree, the right move is to finish the wave, let the orchestrator aggregate, verify that STATE.md is up to date, and then clean up outside of the worktree mechanism.

Toggling Worktrees Off

Sometimes you don’t want worktree-based parallel execution. Setting workflow.use_worktrees to false runs every executor in the main checkout, serially. Use this when:

• Your environment doesn’t support git worktrees cleanly. Some CI runners and some older Windows setups have limitations that make worktrees flaky. Serial execution is more boring but more predictable in those environments.

• You’re debugging and want a single deterministic file tree. Worktrees make it harder to cd into “the” checkout and poke around, because there are several checkouts. Turning them off is a reasonable diagnostic step.

• You intentionally want sequential execution — for example, on a very small machine where the memory cost of running three agents in parallel is worse than the wall-clock cost of running them in series.

The trade-off is loss of parallelism. Phases will take longer to execute. The STATE.md ownership rule still applies in serial mode — the orchestrator is still the only writer — but the risk of races in the main checkout goes away because there is never more than one executor running at a time. If you find yourself fighting worktree edge cases and you don’t specifically need parallelism, the boring serial path is a legitimate choice and not a defeat.

Standardizing Config Across Repos

The single biggest lever for consistency is a shared .planning/config.json template that every repo in your team copies in. Without a template, every repo ends up with a slightly different configuration — one has worktrees enabled, another doesn’t, a third uses a different project_code prefix, a fourth has three agent skill paths the others don’t know about. The teams don’t notice at first, and then six months later somebody asks “why does the billing repo’s GSD output look different from the accounts repo?” and the answer is a sprawl of micro-decisions no one wrote down.

The fix is to commit a canonical template to a shared gsd-templates repo and pull it into every new project via a setup script. The template should pin the fields that matter for team consistency:

• workflow.use_worktrees — typically true for teams that execute phases in parallel.

• workflow.cleanup_worktrees — typically true to avoid accumulating stale worktree directories.

• project_code — the short prefix used for phase directories. Leave this as a template variable so each repo substitutes its own code at setup time.

• Any shared agent-skill paths — if your team has a library of skills living in a shared directory, the paths belong here so every repo picks them up.

• Any shared verifier or reviewer configuration that your team applies uniformly.

What should not go in the team template is anything specific to a single repo: repo-specific build commands, local credentials, one-off overrides. Those belong in the repo’s own config, layered over the template.

MCP Server Scoping, Restated

Chapter 12 touched on this in passing and it’s worth restating because it’s the single most common mistake teams make with MCP in a multi-repo context: do not try to maintain a single global ~/.claude.json for a microservice fleet. Use project-scoped .mcp.json files, one per repo, and commit the non-sensitive parts.

The reason is that microservices are each their own context. The billing service wants a connection to the billing database. The auth service wants a connection to the auth database. If you wire both of those into a single global MCP config, every Claude Code session in every repo gets every database, and the failure modes are confusing — wrong DB picked up, permissions errors from a service that should never have been able to reach that DB in the first place, credentials leaking across contexts. Project-scoped .mcp.json files keep each service’s tool surface minimal and make it obvious from the repo alone what external systems that service talks to.

Workspaces, as we saw in Chapter 12, compose cleanly with this pattern. Each repo inside a workspace carries its own .mcp.json, and a workspace doesn’t reach across its constituent repos to share MCP servers.

Workstream Naming Conventions

Workstream names end up in /gsd:workstreams list output, in .planning/workstreams/ directory listings, in commit messages, and occasionally in PR descriptions. A little discipline here pays off indefinitely:

• Verb-noun format. add-billing, migrate-auth, refactor-orm. Every workstream is doing something, and the name should make that obvious at a glance.

• No timestamps in the name. A workstream called 2026-04-backend-work looks tidy at creation time and looks dreadful six months later when you have fifteen of them and none of the names tell you what the work was. Use creation timestamps via the last touched column in /gsd:workstreams list, not in the name.

• Don’t use a bare ticket ID as the whole name. A workstream called JIRA-1234 is opaque. Pair the ticket ID with a short description: JIRA-1234-billing-flow. You get the ticket traceability and the at-a-glance readability at the same time, and the cost is a handful of extra characters.

• Short is better than long. Aim for workstream names that fit in a reasonable table column. 30 characters is plenty; 60 is painful.

None of these rules are enforced by the tooling. They are the kind of thing you write down in your team’s gsd-templates repo next to the config template and agree to honor.

The project_code Field

A small but underrated piece of team config is the project_code field in .planning/config.json. It’s a short prefix — three or four letters — that GSD uses when it names phase directories and in some default commit message templates. Setting it once:

{
  "project_code": "BCS"
}

means that phase directories come out looking like BCS-phase-1-auth-refactor instead of just phase-1-auth-refactor. When a human later skims a flat directory listing — or reads a commit message that references a phase — the prefix tells them immediately which project the phase belongs to. In a single-repo workflow the prefix is mostly decorative. In a multi-repo team workflow, where a reviewer might be looking at phases from several different services in the same week, the prefix is a small but constant cue that prevents cross-project confusion.

Pick short, memorable codes: BCS for billing-core-service, PAY for payments, ADM for admin-dashboard. Three or four characters, upper-case, no punctuation. Record the mapping somewhere humans can find it — a short table in your team README or in the gsd-templates repo works fine.

Ticket-Based Phase Identifiers

GSD supports tagging phases with external ticket identifiers — the Jira issue, the Linear ticket, the GitHub issue number, whatever your team tracks work in. The mechanism is to record the ticket reference as phase metadata at planning time, and GSD will carry it through to commit message templates and PR descriptions automatically.

The details of which config key holds the ticket reference are version-specific and worth checking against your GSD release’s documentation before you commit to a convention. What matters at the team level is the pattern: choose one ticket system, pick one field name, put it in the team config template, and make sure every planner is using it. When it’s set up, you get traceable commits without any extra effort from the people doing the work — the ticket ID threads through from plan to commit to PR automatically.

The payoff shows up when you’re looking at a six-month-old commit and wondering why it exists. If the commit says “implement session token rotation” and the message also carries PAY-1734, you click through to the ticket and get the full context. Without that thread, you’re archaeologizing.