SkillsAdd

n8n-io/n8n

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.

First seen Mar 11, 2026

Installation

$ npx skills add n8n-io/n8n --skill spec-driven-development
View on skills.sh ↗ GitHub repository ↗

Summary

  • 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.

Similar popular skills

Related neighbors and high-traction skills in the same topics — useful to compare before installing.

agent development Similar name
anthropics/claude-code

This skill should be used when the user asks to "create an agent", "add an agent", "write a sub…

18.1K installs
skill development Similar name
anthropics/claude-code

This skill should be used when the user wants to "create a skill", "add a skill to plugin", "wr…

18K installs
command development Similar name
anthropics/claude-code

This skill should be used when the user asks to "create a slash command", "add a command", "wri…

13.5K installs
hook development Similar name
anthropics/claude-code

This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/…

13.2K installs
apify-actor-development Similar name
apify/agent-skills

Develop, debug, and deploy Apify Actors - serverless cloud programs for web scraping, automatio…

10.3K installs
agent-development Similar name
anthropics/claude-plugins-official

This skill should be used when the user asks to "create an agent", "add an agent", "write a sub…

6.2K installs

Also in this package

Other skills from n8n-io/n8n · top by installs.

npx skills add n8n-io/n8n
n8n:create-pr 866 content-design 482 n8n-conventions 443 n8n:linear-issue 315 n8n:reproduce-bug 315 loom-transcript 311 n8n:conventions 253 n8n:content-design 231 n8n:spec-driven-development 231 n8n:setup-mcps 217

Browse all from n8n-io/n8n

More details

Agent compatibility

Declared targets from SKILL.md / docs. Unmarked agents are not listed — the skill may still install via the CLI.

Claude Code Not declared
Cursor Not declared
Codex Not declared
GitHub Copilot Not declared
Windsurf Not declared
Gemini CLI Not declared
Cline Not declared
OpenCode Not declared

Repository health

Stars 203.8K
License LICENSE.md
Default branch master
Open issues 376
Status Active

Package contents

Files included with this skill beyond the listing page.

  • skill md SKILL.md 3,229 B
  • docs SUMMARY.md 322 B

History

  1. First seen on skills.sh
  2. First recorded snapshot · 150 installs

SKILL.md

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

Read spec → Implement → Verify alignment → Update spec or code → Repeat

Before Starting Work

  1. Find the spec. Search .agents/specs/ for files matching the feature:
ls .agents/specs/
  1. Read the full spec. Understand scope, decisions, API contracts, and

open questions before writing code.

  1. 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: ``markdown - [x] OpenRouter proxy → Direct execution: nodes call OpenRouter directly ``

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?

  1. 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

  1. 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.
  • Split into multiple files when it helps (e.g. separate backend/frontend),

but don't enforce a rigid naming scheme.

When the User Asks to "Self-Review" or "Verify Against Spec"

  1. Read all relevant specs.
  2. Read all implementation files.
  3. Produce a structured comparison:

- Aligned: items where spec and code match - Drift: items where they diverge (fix immediately) - Gaps: spec items not yet implemented (note as future work)

  1. Fix drift, update specs, report gaps to the user.