How to use the Design System GDD Author agent skill

What an agent skill is and what this one does

An agent skill is a folder of instructions that an AI agent loads when you ask it to do a specific task. This skill is a set of instructions that tells the agent how to author a GDD for a single system, following a fixed process rather than improvising the document.

When you invoke it, the agent walks you through each required section of the GDD. For each section it asks design questions, offers options, drafts the section, and writes it to file only after you approve. It also checks dependencies on other systems and can consult specialist agent roles for domain input, while the main session keeps control of all file writes.

• Asks design questions and offers options before drafting
• Drafts one section at a time and writes it only after your approval
• Checks dependencies on other systems
• Can consult specialist agent roles for domain input, whose output is presented to you for a decision
• Saves progress incrementally so an interrupted session can resume at the next unfinished section

Install the design-system skill

The skill is distributed as a ZIP file from the page where you found this guide. Download the ZIP and unzip it. You have two ways to make it available, depending on how you use Claude.

For Claude Code, unzip the skill folder into ~/.claude/skills/ to make it available to you across projects, or into a project's .claude/skills/ folder to make it available only in that project.

For the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

• Claude Code, user-wide: unzip into ~/.claude/skills/
• Claude Code, one project only: unzip into the project's .claude/skills/
• Claude apps: upload the ZIP under Settings → Capabilities → Skills

Check the requirements before you start

The skill is built for Claude Code and expects a project set up around it. It needs the Read, Glob, Grep, Write, Edit, Agent and task tools to be available. Its Bash access is limited to two bundled scripts, yaml-helper.sh and registry.sh.

The skill also reads project files. The source names .claude/hooks/yaml-helper.sh, .claude/docs/config-resolution.md, and a systems-index.md file that provides the categories used to pick specialist agents. If these are missing, the skill's context gathering will not work as designed.

• Claude Code with the required tools available
• Bash access limited to the bundled yaml-helper.sh and registry.sh scripts
• Project files such as .claude/hooks/yaml-helper.sh and .claude/docs/config-resolution.md
• A systems-index.md file for categories
• Works best in a game project, such as the Claude Code Game Studios template

Start a session with a natural request

The skill is invoked by name with a system name, using the argument hint in its definition. Pass the system name, and optionally a review mode of full, lean or solo. If you omit the review mode, the skill uses the review_mode setting resolved from your project configuration, and the --review flag overrides that setting.

The skill's instructions do not document a separate plain-language trigger, so the reliable way to start it is the slash form below. Once it runs, you answer its questions in ordinary language.

• Name the system you are designing, such as combat, crafting or a camera system
• Add --review full, --review lean or --review solo to set the review mode for that run
• Say what you want in plain language when the agent asks design questions

Walk through a GDD section by section

The skill runs in phases. It first parses your arguments and validates them, then gathers context from existing design documents before asking you anything. It then creates an empty GDD file with section headers, so each approved section has a place to be written.

For each section, the agent presents its design questions and approach options, drafts the section, and asks for approval before writing. Each approved section is saved immediately. Every section also checks existing GDDs for conflicts, and any conflict with an approved GDD is flagged rather than silently overridden.

Specialist agents are chosen by the system's category in systems-index.md and the kind of work it involves. For combat, for example, the skill brings in a game designer, with a systems designer for formulas and an AI programmer for enemy AI. Their output is shown to you, and you decide what gets written.

• Phase 1: parse and validate arguments
• Phase 2: gather context from existing GDDs and related documents
• Phase 3: create the file skeleton, after you confirm
• Phase 4: design each section with questions, options, draft and approval
• Phase 5: post-design validation and a hand-off

Resume an interrupted session

If a session is interrupted by compaction, a crash or a new session, the skill recovers from progress it has already saved. It reads production/session-state/active.md to find the current system and which sections are complete, then reads the GDD file at design/gdd/[system-name].md.

Sections with real content are treated as done. Sections still marked [To be designed] are the ones it resumes from, so you do not need to re-discuss completed sections.

• Session state is read from production/session-state/active.md
• The GDD is read from design/gdd/[system-name].md
• Sections marked [To be designed] are picked up next

Safety notes: scripts and network

The skill runs scripts, but only the two bundled ones named in its permissions: yaml-helper.sh (used to resolve configuration) and registry.sh. The source does not indicate that the skill makes network requests, and it is listed as not using the network.

The agent does not write to files on its own authority. The main session owns all file writes, and each write follows your approval. Read the GDD it creates before you build on it, since the skill's output is a draft for your review.

• Bash access is limited to yaml-helper.sh and registry.sh
• Does not use the network, according to its listing
• Agents return proposals only; the main session writes files after you approve

Tips for getting good results

Use the skill for one system at a time, and make sure the system exists in your systems index so the right specialists are chosen. Answer the design questions with specifics, because the drafts reflect your answers. When a conflict with an existing GDD is flagged, decide it explicitly instead of accepting the draft.

Keep the approval habit. The skill is built around collaborative approval at every step, so it is most useful when you review each section rather than trying to skip ahead.

• Work on one system per session
• Make sure the system is listed in your systems index
• Give specific answers to design questions, since drafts follow them
• Resolve any flagged conflicts with existing GDDs before approving
• Review each section before approving it