Agent-Skills.md

Agent Skills: Specification Writing Skill

Specification document creation from gathered requirements and context. Use when requirements are gathered and you need to create a comprehensive spec.

UncategorizedID: oimiragieo/agent-studio/spec-writing

Repository

oimiragieo/agent-studio
oimiragieo
19

Install this agent skill to your local

pnpm dlx add-skill https://github.com/oimiragieo/agent-studio/tree/HEAD/.claude/skills/_archive/dead/spec-writing

Skill Files

Browse the full folder contents for spec-writing.

Download Skill

Loading file tree…

.claude/skills/_archive/dead/spec-writing/SKILL.md

Skill Metadata

Name
spec-writing
Description
'Specification document creation from gathered requirements and context. Use when requirements are gathered and you need to create a comprehensive spec.'

Specification Writing Skill

Overview

Transform gathered requirements and codebase context into a comprehensive, actionable specification document. The spec is the contract between planning and implementation.

Core principle: Synthesize context into actionable spec. No user interaction needed during writing.

When to Use

Always:

  • After requirements gathering is complete
  • When you have codebase context available
  • Before implementation planning begins

Exceptions:

  • Simple changes that don't need formal specs
  • Exploratory work without clear requirements

The Iron Law

NO IMPLEMENTATION WITHOUT A COMPLETE SPEC FIRST

A spec must have ALL required sections before implementation can begin.

Inputs Required

Before writing a spec, ensure you have:

  1. Requirements document - What needs to be built
  2. Project context - Tech stack, structure, patterns
  3. Files to modify - Identified from codebase analysis
  4. Files to reference - Patterns to follow

Workflow

Phase 1: Load All Context

Read all input files to understand the full picture:

# Read requirements
cat .claude/context/requirements/[task-name].md

# Read project context
cat .claude/context/product.md
cat .claude/context/tech-stack.md

# Read any analysis results
cat .claude/context/analysis/[task-name].json 2>/dev/null

Extract from these files:

  • From requirements: Task description, workflow type, acceptance criteria
  • From project context: Services, tech stacks, patterns
  • From analysis: Files to modify, files to reference, patterns

Phase 2: Analyze Context

Before writing, think about:

Implementation Strategy:

  • What's the optimal order of implementation?
  • Which area should be built first?
  • What are the dependencies between components?

Risk Assessment:

  • What could go wrong?
  • What edge cases exist?
  • Any security considerations?

Pattern Synthesis:

  • What patterns from reference files apply?
  • What utilities can be reused?
  • What's the code style?

Phase 3: Write Specification Document

Create the spec with ALL required sections:

# Specification: [Task Name]

## Overview

[One paragraph: What is being built and why]

## Workflow Type

**Type**: [feature|refactor|investigation|migration|simple]

**Rationale**: [Why this workflow type fits the task]

## Task Scope

### Areas Involved

- **[area-name]** (primary) - [role from context analysis]
- **[area-name]** (integration) - [role from context analysis]

### This Task Will:

- [ ] [Specific change 1]
- [ ] [Specific change 2]
- [ ] [Specific change 3]

### Out of Scope:

- [What this task does NOT include]

## Technical Context

### Tech Stack

- Language: [from project context]
- Framework: [from project context]
- Key directories: [from project context]

### How to Run

```bash
[commands from project context]
```

Files to Modify

| File | Purpose | What to Change | | -------- | --------- | ------------------------ | | [path] | [purpose] | [specific change needed] |

Files to Reference

These files show patterns to follow:

| File | Pattern to Copy | | -------- | -------------------------------- | | [path] | [what pattern this demonstrates] |

Patterns to Follow

[Pattern Name]

From [reference file path]:

[code snippet or description]

Key Points:

  • [What to notice about this pattern]
  • [What to replicate]

Requirements

Functional Requirements

  1. [Requirement Name]

    • Description: [What it does]
    • Acceptance: [How to verify]

  2. [Requirement Name]

    • Description: [What it does]
    • Acceptance: [How to verify]

Edge Cases

  1. [Edge Case] - [How to handle it]
  2. [Edge Case] - [How to handle it]

Implementation Notes

DO

  • Follow the pattern in [file] for [thing]
  • Reuse [utility/component] for [purpose]
  • [Specific guidance based on context]

DON'T

  • Create new [thing] when [existing thing] works
  • [Anti-pattern to avoid based on context]

Development Environment

Start Services

[commands from project context]

Required Environment Variables

  • VAR_NAME: [description]

Success Criteria

The task is complete when:

  1. [ ] [From requirements acceptance_criteria]
  2. [ ] [From requirements acceptance_criteria]
  3. [ ] No console errors
  4. [ ] Existing tests still pass
  5. [ ] New functionality verified

QA Acceptance Criteria

CRITICAL: These criteria must be verified by QA before sign-off.

Unit Tests

| Test | File | What to Verify | | ----------- | ---------------- | ------------------------------ | | [Test Name] | [path/to/test] | [What this test should verify] |

Integration Tests

| Test | Areas | What to Verify | | ----------- | ----------------- | ------------------------- | | [Test Name] | [area-a + area-b] | [API contract, data flow] |

End-to-End Tests

| Flow | Steps | Expected Outcome | | ----------- | ------------------- | ----------------- | | [User Flow] | 1. [Step] 2. [Step] | [Expected result] |

QA Sign-off Requirements

  • [ ] All unit tests pass
  • [ ] All integration tests pass
  • [ ] All E2E tests pass
  • [ ] No regressions in existing functionality
  • [ ] Code follows established patterns
  • [ ] No security vulnerabilities introduced

### Phase 4: Verify Spec

After creating, verify the spec has all required sections:

```bash
# Check required sections exist
grep -E "^##? Overview" spec.md && echo "Overview present"
grep -E "^##? Workflow Type" spec.md && echo "Workflow Type present"
grep -E "^##? Task Scope" spec.md && echo "Task Scope present"
grep -E "^##? Success Criteria" spec.md && echo "Success Criteria present"
grep -E "^##? QA Acceptance" spec.md && echo "QA Criteria present"

# Check file length (should be substantial)
wc -l spec.md

If any section is missing, add it immediately.

Phase 5: Save and Signal Completion

Save the spec to the appropriate location:

# Save to context directory
cat > .claude/context/specs/[task-name]-spec.md << 'EOF'
[Spec content]
EOF

Verification Checklist

Before completing spec writing:

  • [ ] Overview section present and clear
  • [ ] Workflow type determined with rationale
  • [ ] Task scope defined with in/out of scope
  • [ ] Files to modify listed with specific changes
  • [ ] Files to reference listed with patterns
  • [ ] Functional requirements documented
  • [ ] Edge cases identified
  • [ ] Implementation notes included
  • [ ] Success criteria defined
  • [ ] QA acceptance criteria complete

Common Mistakes

Generic Content

Why it's wrong: "Implement the feature" is not actionable.

Do this instead: Be specific to this project and task. Use exact file paths.

Missing Tables

Why it's wrong: Empty tables provide no guidance.

Do this instead: Fill in tables with data from context analysis.

No QA Criteria

Why it's wrong: QA agent needs clear criteria to validate.

Do this instead: Include unit, integration, and E2E test expectations.

Integration with Other Skills

This skill works well with:

  • spec-gathering: Provides the requirements input
  • spec-critique: Reviews the spec for issues
  • complexity-assessment: Determines spec complexity for planning

Memory Protocol

Before starting: Read .claude/context/memory/learnings.md

After completing:

  • New pattern -> .claude/context/memory/learnings.md
  • Issue found -> .claude/context/memory/issues.md
  • Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.