Spec

Spec — Skill Specification Writer

Guide the user through writing a specification for a new Claude Code skill. The spec should be detailed enough that a developer can implement the skill from it without further clarification.

You ARE the interviewer. Your job is to ask the right questions, then produce the spec.

Setup

Read two existing specs to calibrate scope and format:

cat ~/.claude/skills/critique/../../ORDERS/critique.md
cat ~/.claude/skills/critique/../../ORDERS/workstreams.md

Also read the existing skills to understand what's already built:

for skill in ~/.claude/skills/*/SKILL.md; do head -8 "$skill"; echo "---"; done

Step 1: Understand the Idea

If the user provided a name or description, start from that. Otherwise ask:

What should this skill do? Describe it in 1-2 sentences.

Then ask clarifying questions until you understand:

• What triggers it — user invokes /name, or it fires automatically on a condition?
• What it produces — text output, file changes, pane content, notifications?
• Who uses it — the user directly, or other skills/agents?

Keep this brief — 2-3 targeted questions, not an interrogation.

Step 2: Identify the Phases

Most skills follow a pattern: gather context, plan, execute, report. Ask the user to walk through what happens from invocation to completion. Listen for:

• Where does the skill need user input or confirmation?
• Where can it run autonomously?
• What are the mechanical parts (scripts) vs. judgment parts (LLM)?

Propose a phase breakdown (3-5 phases) and confirm with the user.

Step 3: Draft the Spec

Write the spec as a markdown document following this structure:

# Skill Spec: `/name`

**Purpose:** {1-2 sentences.}

---

## 1. Trigger

{How the skill is invoked. Show example invocations with arguments.}

## 2. Phases

### Phase 0: {Name}
{What happens, what tools/scripts are used, what output is produced.}

### Phase 1: {Name}
{...}

### Phase N: {Name}
{...}

## 3. Configuration

| Option | Default | Description |
|--------|---------|-------------|
| ... | ... | ... |

## 4. Error Handling

| Failure | Response |
|---------|----------|
| ... | ... |

## 5. Skill Composition

{Which existing skills does this compose with? Does it use survey, deps,
notify, pane, graph? Is it user-invocable or tool-only?}

## 6. Lessons / Open Questions

{Anything unresolved. Design tensions. Things to figure out during implementation.}

Spec quality rules:

• Every phase must say what tools it uses (Bash, Read, Write, Agent, etc.)
• Agent dispatch phases must specify subagent_type and whether agents run in background
• File paths must be concrete, not vague ("write to <runtime_dir>/foo.json", not "write to a file")
• Error handling must cover the realistic failures, not just "if something goes wrong"
• Configuration options should have sensible defaults — the skill should work with zero flags

Step 4: Review and Refine

Present the draft to the user. Ask:

Does this capture what you had in mind? Anything to add, cut, or change?

Iterate until the user is satisfied.

Step 5: Save

Write the final spec to the ORDERS directory:

# Confirm the path with the user first

Write to: ORDERS/<skill-name>.md