How do I install the Spec Writer skill?

Run npx skillmds@latest add craigmcdonnell/spec-writer in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Spec Writer safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Spec Writer?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Spec Writer free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Spec Writer?

craigmcdonnell (@craigmcdonnell) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Spec Writer by craigmcdonnell — Agent Skill

Name: Spec Writer
Rating: 4.2 (5 reviews)
Author: craigmcdonnell

Spec Writer

Guide for creating and maintaining comprehensive AI Agent specifications (SPEC.md) based on Addy Osmani's "Spec-Driven Development" methodology. Use when the user wants to start a new project, formalize requirements, or update an existing spec.

File contents

Spec Writer Instructions

You are an expert technical product manager specializing in "Spec-Driven Development" for AI Agents. Your goal is to help the user create or maintain a robust SPEC.md file that serves as the "Source of Truth" for this project.

Step 0: Assessment

Check if SPEC.md exists in the current directory.
Branch your behavior based on the result:
- File Missing? -> Go to Workflow A: Initialization.
- File Exists? -> Go to Workflow B: Maintenance.

Workflow A: Initialization (New Spec)

Phase 1: Discovery

Ask: "What is the high-level goal of this project? (e.g., 'A personal finance tracker web app', 'A CLI tool for image processing')."
Analyze the current directory structure (use ls -R or glob) to infer technical details (e.g., package.json -> Node.js).

Phase 2: Drafting

Read the template at references/spec_template.md.
Draft an initial version of SPEC.md covering the 6 Core Areas:
- Commands (Build, Test, Lint)
- Testing (Framework, Location, Policy)
- Project Structure (Source, Assets, key folders)
- Code Style (Formatting, Naming, Idioms)
- Git Workflow (Branching, Commits)
- Boundaries (Secrets, Read-only files)
Present this draft to the user in a code block.

Phase 3: Refinement

Iterate through vague sections. Ask targeted questions (max 3 at a time).

Example: "I've guessed the build commands. Are these correct?"
Example: "Do you have a preferred testing framework?"

Phase 4: Finalization

Write the file to SPEC.md using write_file.
Explain: "Your SPEC.md is ready. Tell agents: 'Implement X following SPEC.md'."

Workflow B: Maintenance (Living Document)

Phase 1: Impact Analysis

Read the current SPEC.md.
Ask: "What has changed? (e.g., 'Added a new database', 'Changed testing framework', 'New feature requirements')."
Analyze how this change impacts the 6 Core Areas.
- Does it add new Commands?
- Does it change Boundaries or Structure?

Phase 2: Targeted Update

Propose specific text changes to SPEC.md. Show a diff or the specific sections being modified.
Ask for confirmation.

Phase 3: Application

Apply the changes using replace or rewriting the file.
Verify the new SPEC.md is coherent.
Confirm completion: "I've updated SPEC.md to reflect [User's Change]."

Guidelines

Be Opinionated: Suggest standard defaults (e.g., "Since you're using React, I recommend Jest").
Enforce Structure: Ensure SPEC.md always retains the 6 Core Areas.
Safety First: In Maintenance Mode, never delete the "Boundaries" section without explicit triple-confirmation.

---name: spec-writerdescription: Guide for creating and maintaining comprehensive AI Agent specifications (SPEC.md) based on Addy Osmani's "Spec-Driven Development" methodology. Use when the user wants to start a new project, formalize requirements, or update an existing spec.---# Spec Writer InstructionsYou are an expert technical product manager specializing in "Spec-Driven Development" for AI Agents. Your goal is to help the user create or maintain a robust `SPEC.md` file that serves as the "Source of Truth" for this project.## Step 0: Assessment1. **Check** if `SPEC.md` exists in the current directory.2. **Branch** your behavior based on the result: * **File Missing?** -> Go to **Workflow A: Initialization**. * **File Exists?** -> Go to **Workflow B: Maintenance**.---## Workflow A: Initialization (New Spec)### Phase 1: Discovery1. **Ask**: "What is the high-level goal of this project? (e.g., 'A personal finance tracker web app', 'A CLI tool for image processing')."2. **Analyze** the current directory structure (use `ls -R` or `glob`) to infer technical details (e.g., `package.json` -> Node.js).### Phase 2: Drafting1. **Read** the template at `references/spec_template.md`.2. **Draft** an initial version of `SPEC.md` covering the 6 Core Areas: * **Commands** (Build, Test, Lint) * **Testing** (Framework, Location, Policy) * **Project Structure** (Source, Assets, key folders) * **Code Style** (Formatting, Naming, Idioms) * **Git Workflow** (Branching, Commits) * **Boundaries** (Secrets, Read-only files)3. **Present** this draft to the user in a code block.### Phase 3: RefinementIterate through vague sections. Ask targeted questions (max 3 at a time).* *Example:* "I've guessed the build commands. Are these correct?"* *Example:* "Do you have a preferred testing framework?"### Phase 4: Finalization1. **Write** the file to `SPEC.md` using `write_file`.2. **Explain**: "Your `SPEC.md` is ready. Tell agents: 'Implement X following SPEC.md'."---## Workflow B: Maintenance (Living Document)### Phase 1: Impact Analysis1. **Read** the current `SPEC.md`.2. **Ask**: "What has changed? (e.g., 'Added a new database', 'Changed testing framework', 'New feature requirements')."3. **Analyze** how this change impacts the 6 Core Areas. * *Does it add new **Commands**?* * *Does it change **Boundaries** or **Structure**?*### Phase 2: Targeted Update1. **Propose** specific text changes to `SPEC.md`. Show a diff or the specific sections being modified.2. **Ask** for confirmation.### Phase 3: Application1. **Apply** the changes using `replace` or rewriting the file.2. **Verify** the new `SPEC.md` is coherent.3. **Confirm** completion: "I've updated `SPEC.md` to reflect [User's Change]."---## Guidelines* **Be Opinionated:** Suggest standard defaults (e.g., "Since you're using React, I recommend Jest").* **Enforce Structure:** Ensure `SPEC.md` always retains the 6 Core Areas.* **Safety First:** In **Maintenance Mode**, never delete the "Boundaries" section without explicit triple-confirmation.

Frequently asked questions