commercetools Spec-Driven Development Overlay

This is a commercetools Agent Skill. The Skill source is available on GitHub. You can explore our full Skills catalogue here.

Description

Wire the commercetools skills into a spec-driven development framework — GitHub Spec Kit (.specify/) or OpenSpec (openspec/). Use when user wants to setup or check the status of a spec-driven development framework that touches commercetools.

Installation

Recommended: install the full commercetools plugin. It includes this Skill, every other commercetools Skill, our pre-tuned Subagents, and the commercetools Knowledge MCP — which gives AI live access to the commercetools docs, GraphQL/OpenAPI schemas, and query validation. You only install once; every Skill on this site becomes available in every session.
Install the plugin

In any Claude Code session:

/plugin marketplace add commercetools/commercetools-ai-plugins
/plugin install commercetools@commercetools
Reload plugins

If you've updated the plugin or installed it in another window and need the current session to pick up the latest version:

/reload-plugins
Claude Desktop
Customize -> Personal plugins -> Create plugin -> Add marketplace -> Add commercetools/commercetools-ai-plugins. Then, click on the plugin and click Install.

Instructions Included

SKILL.md

commercetools Spec-Driven Development Overlay

Makes a spec-driven development framework commercetools-aware, so every spec, plan, and task that touches commercetools loads the matching commercetools-* skill first. The framework keeps owning the workflow — this only adds commercetools rules to files the framework already has. It creates no new files.
Detected directoryFramework
.specify/GitHub Spec Kit
openspec/OpenSpec

Both present means both get the overlay.

Workflow

  1. Docs search (required, run first) — Always begin by searching docs for this skill. This is the mandatory grounding step: it gathers the latest verified documentation as context for you (the agent). Do not skip it, and do not replace it with another tool (such as an MCP documentation-search tool). This script optimizes for tuned search results — run this command:
    node scripts/docs-search.mjs \
  --query "<extract key terms from the user's question>" \
  --app-name "<current-app ex: claude, copilot, codex>" \
  --model "<current-model>" \
  --skill-name "commercetools-spec-driven-development" \
  --limit 10

    Query the commercetools areas the project targets, not the framework's own terminology — those results are what let you fill in the plan's "Platform Skills Resolution" table later.

  2. Run the setup script (required, do the work with this) — never hand-edit the framework's files to apply the overlay; the script is idempotent and reversible, hand edits are neither:
    node scripts/setup.mjs
    ArgumentEffect
    (none) or initApply the overlay to every detected framework
    statusReport which blocks are applied; writes nothing
    removeStrip previously applied blocks
    --dry-runPreview init/remove without writing
    --framework speckit|openspecAct on one framework only
    --cwd <dir>Target a project other than the current directory
  3. Report what the script printed, and handle these outcomes:
    • No framework detected (exit 4) — tell the user to run specify init (Spec Kit) or openspec init (OpenSpec) first, then re-run. Do not create those directories yourself.
    • A target file was skipped as missing — the framework is only partially initialized. Name the missing file; do not create it.
    • An anchor was not found — the upstream template changed, so the block was appended at end-of-file instead of at its intended heading. It still works; say the placement is not ideal.
    • Applied, or already up to date — state which files changed and stop.

What the overlay adds

FrameworkFileAdds
Spec Kit.specify/memory/constitution.mdNon-negotiable articles: resolve the platform skill, annotate tasks, never invent API surface
Spec Kit.specify/templates/plan-template.mdA "Platform Skills Resolution" table mapping each architectural area to its skill
Spec Kit.specify/templates/tasks-template.mdThe [SKILL: <name>] task-grammar extension
OpenSpecopenspec/config.yamlcontext: guidance plus rules: for the proposal and tasks artifacts
Each block is fenced by commercetools-spec-extension:begin / commercetools-spec-extension:end markers. Re-running init replaces a block in place rather than duplicating it, and remove restores the file to its original bytes.

Checklist

  • node scripts/docs-search.mjs ran first and its results were used as grounding
  • The framework was initialized first (.specify/ or openspec/ exists)
  • node scripts/setup.mjs ran and reported the blocks it applied
  • No target was skipped as missing, and no anchor warning went unmentioned
  • For OpenSpec, config.yaml has no duplicate context: or rules: keys