Agent skill · software engineering · n8n-io
n8n:spec-driven-development
Keeps implementation and specs in sync. Use when working on a feature that has a spec in .agents/specs/, when the user says /spec, or when starting implementation of a documented feature. Also use when the user asks to verify implementation against a spec or update a spec after changes.
Why this skill is useful
Provides a structured process for maintaining alignment between implementation and specifications, which includes specific commands and conventions not commonly known.
What it needs
About 2k tokens when loaded. Last updated 2026-08-07. 199,638 stars on the source repository.
What this skill does
Spec-Driven Development Specs live in .agents/specs/. They are the source of truth for architectural decisions, API contracts, and implementation scope. Implementation and specs must stay in sync — neither leads exclusively. Core Loop Before Starting Work 1. Find the spec. Search .agents/specs/ for files matching the feature: 2. Read the full spec. Understand scope, decisions, API contracts, and open questions before writing code. 3. If no spec exists and the task is non-trivial (new module, new API, architectural change), ask the user whether to create one first. During Implementation Reference spec decisions — don't re-decide what the spec already settled. When you diverge from the spec (better approach found, user requested change, constraint discovered), update the spec immediately in the same session. Don't leave spec and code out of sync. Tick off TODO checkboxes (- [ ] → - [x]) as items are completed. Strike through or annotate items that were deliberately skipped or replaced, with a brief reason: After Completing Work Run a spec verification pass: 1. Re-read the spec alongside the implementation. 2. Check each section: Do API endpoints in spec match the controller? Do config/env vars in spec match the config class? Does the module structure in spec match the actual file tree? Do type definitions in spec match @n8n/api-types? Are all TODO items correctly checked/unchecked? 3. Update the spec for any drift found. Common drift: New files added that aren't listed in the structure section API response shapes changed during implementation Config defaults adjusted Architectural decisions refined 4. Flag unresolved gaps to the user — things the spec promises but implementation doesn't deliver yet (acceptable for MVP, but should be noted). Spec File Conventions One or more markdown files per feature in .agents/specs/. Keep specs concise. Use tables for mappings, code blocks for shapes. Use ## Implementation TODO with checkboxes to track progress. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills n8n-io/spec-driven-development