Requirements Engineering Agent Skill

License: MIT Agent Skills

A Claude Code skill that transforms vague or incomplete requirements into well-defined, testable specifications using BDD, Use Cases, Model Specs, Payload Contracts, flowcharts, and architecture diagrams.

Who is this for?

Anyone who encounters vague requirements and needs to transform them into implementable specifications:

  • Product Managers defining feature requirements
  • Software Teams bridging business and technical needs
  • Developers needing clear specs before writing code
  • Technical Writers structuring project documentation

Installation

Install via skills.sh:

npx skills add SwiftyJourney/requirements-engineering-skill

Compatible Agents

What the Skill Covers

The Feature Specification Artifacts

A feature draws from this catalog — include the artifacts its behavior warrants, not a fixed quota. The full set fits a non-trivial networked feature; an online-only or model-reusing feature ships fewer (e.g. no offline narrative, cache use case, or Cancel course):

  1. BDD Narrative — Define who, what, why per user type
  2. Acceptance Criteria — Given/When/Then scenarios
  3. Use Cases — Step-by-step system behavior (Data/Primary/Error/Cancel)
  4. Model Specs — Property/Type tables for domain entities
  5. Payload Contract — HTTP method + path + response JSON
  6. Flowchart — Decision flow with error branches
  7. Architecture Diagram — Module dependency graph

The 6-Step Process

  1. Identify — Recognize vague requirements
  2. Clarify — Ask Who/What/Where/When/Why/How
  3. Specify BDD — Write narratives and acceptance criteria
  4. Define Use Cases — Procedural steps with cancel courses
  5. Model & Contract — Property/Type tables and JSON payloads
  6. Visualize & Document — Diagrams and feature specification

Key Patterns

  • Clarify before you specify — Run the lousy-ticket teardown; BDD's value is the conversation that eliminates assumptions, not the Gherkin
  • Prototype to settle what discussion can't — A throwaway spike with hard-case data, never promoted to production
  • Cancel courses — First-class cancellation requirements for async operations
  • Separation of concerns — Extract focused use cases (Load vs Validate vs Cache)
  • Domain language alignment — Consistent terminology across all artifacts
  • Incremental feature development — Self-contained feature blocks
  • Living specification — Requirements evolve with code

Skill File Structure

skills/requirements-engineering/         # the skill — this is what ships
├── SKILL.md                             # Hub + diagnostic table + gotchas + reference router
└── references/
    ├── clarifying-questions.md          # Lousy-ticket teardown, question bank, answer-to-artifact
    ├── bdd-narratives.md                # BDD stories, narratives, acceptance criteria
    ├── use-cases.md                     # Use case structure, courses, CQS, separation of concerns
    ├── model-specs-and-contracts.md     # Model specs, payload contracts, abstract core, JSON examples
    ├── diagrams.md                      # Flowcharts, four-type dependency notation, architecture, state
    ├── domain-language.md               # Terminology alignment, ubiquitous language, renaming
    ├── feature-specification-workflow.md # End-to-end workflow, traceability
    └── worked-example.md                # A complete assembled requirements set (image feed + comments)
docs/                                    # Quickstart, installation, contributing (repo-only)
evals/                                   # Trigger eval queries + output-quality test cases (repo-only)
.claude-plugin/                          # plugin.json + marketplace.json (repo-only)

Related Skills

  • iOS Architecture Expert — Clean modular architecture: composition root, protocol boundaries, generic presenters, Swift 6 concurrency
  • SwiftUI Expert — SwiftUI view code: state, composition, performance, animations, accessibility
  • SwiftUI ⇄ UIKit Interop — Bridge SwiftUI and UIKit: hosting controllers, representables, data across the boundary
  • Swift Language Expert — Non-obvious Swift language & standard-library techniques
  • Swift Testing Expert — Swift Testing syntax, XCTest migration, test doubles, deterministic async tests

Credits

Requirements methodology and artifact format distilled from a real-world iOS case study (an image-feed app) whose README documents the canonical BDD narratives, use cases, payload contracts, and dependency diagrams.

License

MIT — see LICENSE.