specification

Write or update SPEC.md files with structured requirements and scenarios.

Updated Nov 17, 2025
One-click install
npx skills add https://github.com/craigtkhill/atui-tools --skill specification
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: specification
Source: https://github.com/craigtkhill/atui-tools/tree/main/skills/specification
Command: npx skills add https://github.com/craigtkhill/atui-tools --skill specification

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solves?

This Skill eliminates ambiguity and incompleteness in feature definitions by providing a structured, conventional way to write specifications. It ensures that all stakeholders understand precisely what needs to be built, reducing miscommunication, costly rework, and project scope creep.

Core Features & Use Cases

  • Standardized Spec Format: Enforces a consistent structure for feature headers, user stories, requirements, and scenarios, making specs easy to read and understand.
  • Atomic & Testable Requirements: Guides you to write clear, specific requirements that are easy to test and implement, improving development efficiency.
  • Given/When/Then Scenarios: Promotes behavior-driven development by structuring scenarios to describe user actions and expected outcomes, ensuring comprehensive coverage.
  • Use Case: When starting any new feature or project, use this skill to draft a comprehensive spec.md file, ensuring all requirements are captured clearly and approved before development begins, saving time and resources.

Quick Start

Start a new feature. Use the specification skill to write the initial spec.md file for a user story about user authentication.

Frequently Asked Questions about specification

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write clear feature specifications that reduce miscommunication?

Feature specifications establish a shared understanding of requirements before development. Write structured specifications with a feature header, atomic requirements (one per line), and Given/When/Then scenarios to ensure all stakeholders align on what needs to be built, reducing rework and scope creep.

What's the best way to organize requirements and user stories in a specification?

Organize specifications using a standardized format: feature header at the top, requirements section with one testable requirement per line, and scenarios section with Given/When/Then structures. This atomic approach makes requirements easy to test, implement, and verify completion.

How do I structure specifications for behavior-driven development?

Use Given/When/Then scenario format to describe user actions and expected outcomes. This BDD structure ensures comprehensive coverage of feature behavior, makes specifications executable as tests, and aligns product requirements with technical acceptance criteria.

When should I create a specification before starting development?

Create specifications when starting any new feature or project. Writing a comprehensive spec.md file before development captures all requirements clearly, gets stakeholder approval upfront, and saves time by preventing ambiguity-driven rework and mid-project scope changes.

What makes a requirement testable and implementable?

Testable requirements are atomic, specific, and written from the user's perspective. Each requirement should describe one behavior, be independently verifiable, use clear action verbs, and avoid ambiguous language so developers can implement and testers can validate without guesswork.

Can I use specification discipline across new features and code changes?

Yes, apply specifications to both new features and changes to existing features. Place spec.md files alongside code to maintain specification discipline, enforce consistent structure, track requirements as code evolves, and ensure every change satisfies defined functional and technical requirements.