Guide · Agent skill
How to use the Design Doc Drafter agent skill (egm-draft)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The egm-draft skill is an instruction file that tells an AI agent how to help you write a technical design document one section at a time. It works from a concepts brief produced by the earlier egm-brainstorm step, or from notes you provide. This guide explains what the skill makes the agent do, how to install it, how to trigger it, and what to watch for.
Design Doc Draftergoogle/elephant-goldfish-model · Apache-2.0 Download the skill Quick start
- 1Get the skill files. Download the egm-draft ZIP from the directory page and unzip it. Confirm the folder contains SKILL.md.
- 2Place the folder. Move it into ~/.claude/skills/ for personal use or into your project's .claude/skills/ folder for one project.
- 3Prepare your input. Have a concepts_brief.md or discussion_summary.md ready, or write your requirements and proposed solution as notes.
- 4Ask for the skill by name. Start a chat with your agent and request the egm-draft skill, pointing it at your context file or notes.
- 5Review each section. Open design_draft.md, read the drafted section, and add inline comments if needed.
- 6Approve or request revisions. Choose the approval option in the agent's question. Repeat for each section until the draft is complete.
- 7Choose architecture options yourself. When the agent presents options with trade-offs, pick one. The skill will not choose for you.
What is an agent skill and what does egm-draft make the agent do?
An agent skill is a folder with a SKILL.md file that an AI agent such as Claude Code or Codex loads to learn a specific workflow. The skill is the second step in the Elephant-Goldfish (EGM) feature flow, after brainstorming. It is for users who already have requirements and a proposed solution and are ready to write a design doc.
The agent writes the draft into a file named design_draft.md in your working directory rather than in the chat pane. After drafting each section it stops, tells you the file path, and asks you to approve the section or request changes. The skill also asks the agent to stress-test your ideas, list counter-arguments, and leave architecture choices to you by presenting up to three options with trade-offs and no recommended default.
- Reads a concepts_brief.md or discussion_summary.md from an earlier step, or uses your notes
- Writes the draft to design_draft.md and reviews it section by section
- Pauses for approval after each section, and applies inline comments in design_draft.md
- Presents architecture options with trade-offs instead of picking one
Install the egm-draft skill (ZIP download or Claude apps)
Download the egm-draft ZIP from the directory page. Then choose one of two install locations. For a personal install available in every project, unzip the folder into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. After unzipping, the folder should contain SKILL.md, references/design_doc.md and agents/openai.yaml.
If you use the Claude apps instead of Claude Code, go to Settings, then Capabilities, then Skills, and upload the skill there.
- Personal: ~/.claude/skills/
- Project only: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills → upload
Trigger the skill with a natural request
The skill's metadata describes it as used when you are ready to write a design doc after aligning on requirements and solution. In practice, ask the agent in plain language to start drafting the design doc for your feature and mention your predecessor file or your notes. The skill is marked as not auto-invoked, so ask for it explicitly by name, such as asking the agent to use the egm-draft skill.
Give the agent a context file if you have one. If you do not, it looks for concepts_brief.md or discussion_summary.md in the working directory or the conversation artifact directory, in that priority order. If it finds neither, it can work from notes you type.
- Example: "Use the egm-draft skill to start the design doc from concepts_brief.md."
- Example: "Use egm-draft. Here are my requirements and proposed solution: ..."
- Example: "Use egm-draft with docs/designs/export_feature.md as the context file."
Work through the approval loop
Each section follows the same pattern. The agent drafts the section into design_draft.md, summarises two or three key decisions in chat, links the file, and presents a single-choice question. You can approve the section and move on, or request revisions. For revisions you can write instructions in chat or leave inline comments in the file. Positive comments tell the agent to keep a passage, and negative comments tell it to revise or remove content.
If you choose to request revisions without writing anything, the agent asks you in chat what to change rather than guessing.
- Approve: the agent applies any inline comments and moves to the next section
- Request revisions: the agent applies your comments or write-in notes and asks again
- You can return to earlier phases if you forgot something, but the skill expects you to confirm before it moves on
What the skill needs and what it does not do
You need an AI agent that loads SKILL.md skills, such as Claude Code or Codex. You also need either a predecessor file such as concepts_brief.md or discussion_summary.md, or your own notes. The skill refers to companion files that are not included in the review material: docs/codex.md, docs/claude.md and resources/execution_instructions.md. The agent is told to read these, so the skill may not behave as described unless they are present in your setup.
The skill declares that it runs no scripts and uses no network access. It works by reading and writing files in your working directory.
- Runs scripts: no
- Uses network: no
- Writes to: design_draft.md in the working directory or artifact directory
- Companion files referenced but not included: docs/codex.md, docs/claude.md, resources/execution_instructions.md
Tips for getting useful output
Bring a clear problem statement, requirements and a proposed solution. The skill is built to challenge them, so weak inputs produce a longer list of objections rather than a finished document. The template it uses is references/design_doc.md, which includes sections for Overview, The Problem, Goals, Non-Goals and Open Questions.
Expect the agent to lead with what is wrong or missing. Answer the architecture options yourself. If you ask the agent to just pick one, it restates the trade-offs and asks again.
- Start from a concepts brief when you have one, so the agent does not reconstruct the problem
- Keep Goals measurable and Non-Goals explicit, since the template treats them as success criteria and scope limits
- Use inline comments in design_draft.md for precise edits to specific passages
What people use it for
- Turning a concepts brief from an earlier brainstorm into a section-by-section design doc
- Stress-testing a proposed feature design before it goes to a review meeting
- Drafting Goals and Non-Goals with the agent challenging vague or unmeasurable wording
- Working through architecture trade-offs such as data model or storage options, with the decision left to you
Frequently asked questions
Is the egm-draft skill free to use?
The skill is licensed under Apache-2.0, as stated in its SKILL.md. The source material does not give pricing for the agent tools you run it in, so check the terms of the agent product you use.
What do I need to run egm-draft?
You need an AI agent that loads SKILL.md skills, such as Claude Code or Codex. You also need a predecessor file like concepts_brief.md or discussion_summary.md, or your own notes.
Where do I put the egm-draft skill files?
Unzip the download into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project for that project only. In the Claude apps, go to Settings, Capabilities, Skills and upload it.
Does egm-draft run scripts or access the internet?
According to its metadata, the skill runs no scripts and uses no network access. It reads and writes files such as design_draft.md.
Can the agent choose the architecture for my design doc?
No. When a decision has more than one defensible answer, the skill presents up to three options with trade-offs and asks you to choose. If you ask it to just pick one, it presents the same choice again.
Is egm-draft a good alternative to writing a design doc with a general chatbot?
It suits engineers following the Elephant-Goldfish flow who want section-by-section approval and critical review. For quick one-off notes or a document where you want the agent to decide, the step-by-step gating adds overhead and a different approach fits better.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use egm-draft if you already have requirements and a proposed solution, follow the Elephant-Goldfish flow, and want an agent that challenges your design and waits for your approval at each section. Skip it for quick notes, for projects not using the EGM flow, or if you want the agent to make architecture decisions for you.
Download the skill