skills.rest
inkeep
inkeepOFFICIAL
Explore all skills by this author →
Website𝕏@inkeepGitHub

write-a-spec

Writes implementation specs under specs/ from accepted proposals with decision logs and test plans.

3.9k|256|Updated Jun 3, 2026
Search Tags:#implementation planning#migration plan#decision log#Technical Design#software lifecycle#OpenKnowledge#Spec
One-click install
npx skills add https://github.com/inkeep/open-knowledge --skill write-a-spec
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: write-a-spec
Source: https://github.com/inkeep/open-knowledge/tree/main/packages/server/assets/skills/packs/software-lifecycle/write-a-spec
Command: npx skills add https://github.com/inkeep/open-knowledge --skill write-a-spec

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Turning an accepted proposal into a buildable implementation spec is where projects quietly go wrong: specs get written against an imagined system, open questions get silently guessed, and one-way-door decisions lose their reasoning. This Skill enforces a gated, step-by-step workflow that produces a spec grounded in the actual codebase, with its trade-offs and unknowns recorded.

Core Features & Use Cases

  • Mandatory execution order: Find the parent proposal, map the current system from real code, pass a scoping gate, then draft Goals, Non-goals, Design, Migration, and Test plan in a specs/NNN-name/ folder.
  • Decision Log and Open Questions: Append a Decision Log capturing one-way-door choices with reversal conditions, plus a live Open Questions backlog with closing evidence and deciders.
  • Plan and task breakdown: Generate plan.md and tasks.md from templates when the spec is greenlit, with dependency-ordered, independently verifiable tasks.
  • Use Case: After a payment-retries proposal is accepted, ask the agent to scope the feature; it reads the existing billing code, proposes goals and non-goals for confirmation, then writes specs/004-payment-retries/spec.md with a migration plan and decision log.

Quick Start

Ask the agent to turn the accepted proposal into an implementation spec for the feature you want to build.

Frequently Asked Questions about write-a-spec

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

FAQPage Schema
How do I write an implementation spec from an accepted proposal?▼

Invoke the skill after a proposal is accepted; it finds the parent proposal, maps the current system from real code, confirms scope with you, then creates specs/NNN-name/spec.md from a template with Goals, Non-goals, Design, Migration, and Test plan sections.

What is a decision log in a software spec?▼

A Decision Log records one-way-door choices made during design, each with options considered, the choice, rationale, date, and a reversal condition. This skill appends it to spec.md so future owners understand why the system is shaped the way it is.

Can I write a spec without an accepted proposal?▼

The skill treats a missing or unaccepted proposal as a hard gate and stops. You can either frame a proposal first with the sibling frame-a-proposal skill, or explicitly acknowledge the risk and proceed, which gets recorded in the Decision Log.

Does this skill work with Claude Code or other AI agents?▼

Yes, it works with any agent host that has the OpenKnowledge MCP server configured. It is installed project-locally via the ok seed --pack software-lifecycle command.

When should I not use this spec-writing skill?▼

Do not use it to frame a proposal or PRD before acceptance, record architecture decisions in decisions/, write postmortems, or review designs. Those are handled by separate sibling skills in the software-lifecycle pack.

Related Skills

Explore More Software Engineering Skills→
quaid-appquaid-app
3

architectural-proposals

Draft structured architectural proposals with problem statements, decisions, and risks.

Official
Advanced
DIO0550DIO0550
1

spec-implement

Automate numbered spec implementation by applying plans from .specs folders.

Community
Intermediate
WizarckWizarck
2

bmad-extract-lessons-from-adrs

Analyze ADRs, retrospectives, and postmortems to summarize recurring failure patterns.

Community
Advanced
robwestzrobwestz

heavy-file-ingestion-codex

Convert heavyweight PDFs, Office documents, and spreadsheets into markdown or CSV artifacts.

Community
Intermediate