Agent-Skills.md

Agent Skills: Writing Specs

Writes and manages spec files in specs/ with mandatory duplicate search, conflict detection, and a structured final report. Use when user asks to create a spec, update a spec, write a spec, or mentions 스펙 생성, 스펙 업데이트, 스펙 작성, 스펙 만들어줘. Proactively trigger whenever the request involves specification documents, even if the user never says spec.

UncategorizedID: devstefancho/claude-plugins/writing-specs

Repository

devstefancho/claude-plugins
devstefancho
111

Install this agent skill to your local

pnpm dlx add-skill https://github.com/devstefancho/skills/tree/HEAD/skills/spec-driven/writing-specs

Skill Files

Browse the full folder contents for writing-specs.

Download Skill

Loading file tree…

skills/spec-driven/writing-specs/SKILL.md

Skill Metadata

Name
writing-specs
Description
Writes and manages spec files in specs/ with mandatory duplicate search, conflict detection, and a structured final report. Use when user asks to create a spec, update a spec, write a spec, or mentions 스펙 생성, 스펙 업데이트, 스펙 작성, 스펙 만들어줘. Proactively trigger whenever the request involves specification documents, even if the user never says spec.

Writing Specs

Manage spec files in specs/ with conflict detection and a concise final report.

Hard Rules

  • Template-driven. Every spec follows templates/spec-template.md exactly. No extra sections, no freestyle content.
  • Search before write. Never create or update a spec without running Phase 1.
  • One spec = one task. A request spanning multiple concerns becomes multiple specs.
  • Never auto-modify outdated specs. Propose updates, then wait for confirmation.
  • Always end with the report. No silent operations.

Directory Rules

  • Specs live in specs/ at the project root. Filenames are lowercase-with-hyphens.
  • Default path: specs/phase-N/NN-name.md — the convention writing-tasks consumes; using it makes the spec→task handoff zero-friction.
    • phase-N: 1-indexed milestone number, monotonically increasing across the project, never reset.
    • NN: 2-digit index within the phase, starting at 01. Example: specs/phase-1/01-jwt-authentication.md.
  • Alternatives (specs/{name}.md, specs/{subdir}/{name}.md) only when no writing-tasks integration is planned.
  • Max 1-depth subdirectories. Create subdirs or new phases only on explicit request, or when 5+ specs share a clear category.

Auto-pick phase + NN when the user does not specify:

  1. Glob specs/phase-*/ — no phases → phase-1.
  2. Use the highest existing phase, unless the user signals a new milestone → create phase-{N+1}.
  3. Glob specs/phase-N/*.md — new spec gets highest existing NN + 1, zero-padded.
  4. Spec belongs to a clearly different milestone? Ask via AskUserQuestion before creating a new phase.

Phase 0 — Resolve the input

| Argument shape | Resolution | |---|---| | brain-storm/**.md path | Read it. Summary / Motivation / Proposed Approach become the spec source; the idea title becomes the spec H1. | | Any other markdown path | Read it; its content is the spec source. | | Bare title or keyword | Glob brain-storm/**/*.md, match H1 (case-insensitive) then filename slug. One match → use it. Multiple → AskUserQuestion. Zero → treat as freestyle. | | Freestyle text, or no argument | Use conversation context. Empty → ask via AskUserQuestion. |

From a brain-storm source: Summary seeds Purpose; Proposed Approach bullets seed Requirements (prune to 3-5 concrete items) and the prose Approach. Wireframe and Open Questions are NOT copied — list them under "Carried over" in the report.

  • [ ] Input resolved to exactly one source

Phase 1 — Search (mandatory)

  1. Glob specs/**/*.md to list all spec files.
  2. Extract 3-5 key nouns from the request (skip generic words like "system", "feature", "add", "update").
  3. Grep each keyword across the found specs.
  4. Classify: Exact match (same topic) · Related (2+ shared keywords or adjacent topic) · Outdated (references files that no longer exist — verify with Glob).

No specs/ directory yet → skip to Phase 3.

Phase 2 — Decide

  • No related specs → proceed to create.
  • Exact match → ask: "이미 동일한 스펙이 존재합니다: {path}. 업데이트할까요, 새로 생성할까요, 아니면 취소할까요?"
  • Related specs → show the list and ask: "관련 스펙이 발견되었습니다. 어떻게 진행할까요?"
  • Outdated specs → "다음 스펙이 outdated 상태입니다 (참조 파일 없음). 함께 업데이트할까요?"

All decisions go through AskUserQuestion.

Phase 3 — Write

  1. Read templates/spec-template.md and fill it strictly.
  2. Resolve the destination with the auto-pick rules above; write under specs/.
  3. On update, preserve every section the user did not ask to change.

Section limits (enforced, not suggested): Purpose 1-2 sentences, no bullets · Requirements 3-5 bullets, one concrete requirement each · Approach 2-5 sentences, no code · Verification 2-5 testable bullets.

Phase 4 — Outdated cleanup

For each outdated spec found in Phase 1: identify the broken references, propose specific updates, apply only after user confirmation. Never auto-modify.

Phase 5 — Report

Fill templates/report-template.md and output it as the final message: Action (Created/Updated), File (relative path), Title (spec H1), Search Results (each related/outdated spec, or "No related specs found"), Changes ("New spec created" or update summary), Next Steps (one actionable suggestion).

Non-interactive mode

If AskUserQuestion is unavailable (auto mode, headless, scheduled), apply the defaults in non-interactive.md and echo every defaulted decision in the Phase 5 report.