How do I install the N8n:spec Driven Development skill?

Run npx skillmds@latest add n8n-io/n8n-spec-driven-development in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is N8n:spec Driven Development safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with N8n:spec Driven Development?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is N8n:spec Driven Development free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published N8n:spec Driven Development?

n8n-io (@n8n-io) published this skill. Their other Agent Skills are listed on their SkillMD profile.

N8n:spec Driven Development by n8n-io

Name: N8n:spec Driven Development
Rating: 4.666666666666667 (3 reviews)
Author: 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.

n8n-io Updated Sep 9, 2026

File contents

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

Find the spec. Search .agents/specs/ for files matching the feature:

ls .agents/specs/

Read the full spec. Understand scope, decisions, API contracts, and open questions before writing code.
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:
```
- [x] ~~OpenRouter proxy~~ → Direct execution: nodes call OpenRouter directly
```

After Completing Work

Run a spec verification pass:

Re-read the spec alongside the implementation.
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?
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
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"

Read all relevant specs.
Read all implementation files.
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)
Fix drift, update specs, report gaps to the user.

--- name: n8n-spec-driven-development description: 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. --- # 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: ```bash ls .agents/specs/ ``` 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: ```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? 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. - 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) 4. Fix drift, update specs, report gaps to the user.

Frequently asked questions