Index of every page on this site: llms.txt
All skills
n8n-io avatar

/spec-driven-development

@273d130 official
by n8n - Workflow Automationn8n-io/n8n211k stars
61,599
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/n8n-io/n8n/spec-driven-development

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈78 tokens for metadata: the name and description. ≈721 when used: this file.

Description uses 4.0% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈317 characters, or 4.0%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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.

  2. 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:

  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.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts8mo4 checks · Risk SAFE
  • Gen Agent Trust Hub8mo

    This skill is safe and facilitates a specification-driven development workflow by helping the agent synchronize implementation with design documents stored in the local workspace. No malicious patterns or unauthorized external communications were detected.

  • Socket8mo

    No alerts

  • Snyk8mo

    Risk: LOW · No issues

  • Runlayer8mo

    1 file scanned · No issues

Signed by skilld at 273d130. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 5 months ago
  • Documentation
  • n8n
  • spec-driven
  • development-workflow
  • verification
  • architecture
  • api-design
  • implementation

README badge

README badge for n8n-io/n8n/spec-driven-development

Keeps implementation and specs in sync by treating `.claude/specs/` markdown files as source of truth for architecture and API contracts. Use when starting a feature with an existing spec, when the user requests `/spec`, or when verifying implementation matches documented design. Includes a core loop for reading specs, implementing, verifying alignment, and updating specs or code as needed.

Generated from the current SKILL.md.

When should I use this skill?
Use this skill when working on a feature that has a spec in .claude/specs/, when the user says /spec, or when starting implementation of a documented feature. Also use it to verify implementation against a spec or update a spec after changes.
What happens if I diverge from the spec during implementation?
Update the spec immediately in the same session to reflect the divergence. Do not leave spec and code out of sync — they are both sources of truth.
What should I do after completing work?
Run a spec verification pass: re-read the spec alongside implementation, check each section for drift (API endpoints, config vars, module structure, types), update the spec for any drift found, and flag unresolved gaps to the user.
What if no spec exists for the feature?
If the task is non-trivial (new module, new API, architectural change), ask the user whether to create a spec first before implementation.
How should I track progress in the spec?
Use `## Implementation TODO` sections with checkboxes, marking items as complete (`- [x]`) and striking through deliberately skipped items with a brief reason for the change.

Generated from the current SKILL.md. These answers refresh after source changes.