Spec Authoring Skill

Overview

This skill focuses on writing clear, comprehensive specifications and requirements documents. The output follows the format defined in specs/requirements.md .

Document Format

Requirements documents consist of three main sections:

1. Introduction

Brief description of what the project does and its main purpose. Focus on the problem being solved and the overall goal.

Example:

A task management application that helps remote teams coordinate their work asynchronously...

2. Glossary

Define key terms using Term_Case format for consistency:

Example:

Task_Board: The main interface showing all tasks organized by status columns Time_Entry: A record of time spent working on a specific task

3. Requirements (User Stories)

Each requirement follows this format:

Requirement N

User Story: As a [type of user], I want [goal/objective], so that [benefit/value].

Acceptance Criteria

• THE [System/Component] SHALL [specific action or behavior]
• WHEN [condition], THE [System/Component] SHALL [response or action]
• WHERE [condition exists], THE [System/Component] SHALL [handling behavior]

Key Capabilities

• Gathering and documenting requirements through user stories

• Writing acceptance criteria using THE/WHEN/WHERE format (RFC 2119 style)

• Creating clear glossaries with domain-specific terminology

• Defining what needs to be built without specifying how

Best Practices

• User-centric: Frame requirements as user stories with clear value proposition

• Precise language: Use THE/WHEN/WHERE format for testable acceptance criteria

• Complete glossary: Define all domain-specific terms upfront

• Focused scope: Each requirement should address a single capability

• Measurable: Acceptance criteria must be objective and verifiable

• Edge cases: Include error handling and boundary conditions in criteria

Working with the Template

• Read the template: Review specs/requirements.md for structure and examples

• Replace examples: Remove the task management example, keep the structure

• Fill Introduction: Describe your project's purpose in 2-3 sentences

• Build Glossary: List key terms as you identify them (use Term_Case)

• Write User Stories: Start with highest priority requirements

• Define Criteria: Use SHALL statements, include happy path and errors

• Iterate: Review with stakeholders and refine

Example Requirement

Requirement 1

User Story: As a team lead managing a distributed team, I want to create and assign tasks to team members, so that everyone knows their responsibilities and deadlines.

Acceptance Criteria

• THE Task_Board SHALL display all tasks organized in columns (To Do, In Progress, Done)
• WHEN a task is created, THE system SHALL require a title, description, and assignee
• THE Task_Board SHALL support drag-and-drop to change task status
• THE system SHALL send email notifications to assignees when tasks are assigned
• WHERE a task lacks required fields, THE system SHALL prevent creation and display validation errors

Related Skills

• Design Authoring: Converts requirements into technical designs

• Task Breakdown: Creates implementation tasks from design

Tips for Agents

• Reference glossary terms consistently throughout the document (use Term_Case)

• Number requirements sequentially using headings (### Requirement 1, ### Requirement 2, etc.)

• Keep user stories concise but complete (one sentence each for As/I want/So that)

• Ensure every acceptance criterion is independently verifiable

• Link to this template when user asks about requirements format