Skip to content

Spec

The spec skill manages multilingual specifications under spec/. Each spec has its own folder with exactly one file per configured language. One language is canonical; the others are translations kept structurally and semantically in sync via this skill.

When to use

  • "write a spec for X," "new specification"
  • "is X already covered?" (duplicate check)
  • "translate the spec"
  • "regenerate the spec index"
  • "check for drift"

On-disk layout

spec/
├── .spec-config.yml
├── README.md                       # autogenerated index
└── [<topic>/]<slug>/
    ├── en.md                       # canonical
    └── de.md                       # translation

Topic folders group related specs (for example spec/claude/, spec/api/). Exactly one level of topic nesting is allowed; without a topic, a spec lives directly under spec/<slug>/.

Defaults and configuration

Key Default
canonical_language en
languages [en, de]
spec_root spec

Overridable via spec/.spec-config.yml:

canonical_language: en
languages: [en, de]
spec_root: spec

If the file is missing, defaults apply. It's created on the first create operation so downstream projects have a visible extension point.

Operations

Create

  1. Take the user's description (any language).
  2. Duplicate check first: clear overlap → stop and ask: extend, supersede, or create new.
  3. Draft the canonical spec from templates/spec.template.md, filling each section with user input. Mark unknowns explicitly instead of inventing.
  4. Translate into every other configured language. Structure stays identical. RFC 2119 keywords stay English and are glossed in-language, for example MUSS [MUST], SOLLTE [SHOULD], KANN [MAY].
  5. Write all language files in one operation—never half-written.
  6. Regenerate the index.

Update / prevent drift

  • Canonical version is the single source of truth.
  • Edit on canonical → regenerate every translation.
  • Edit directly on translation → warn. Options: (a) lift the semantic change into the canonical and regenerate, (b) discard the translation edit and regenerate from canonical.

Drift check

For every spec folder, compare translations to canonical:

  • Same headings, same order
  • Same count of requirement bullets and acceptance-criteria checkboxes
  • Same requirement IDs / ordering

Mismatches reported; regeneration offered.

Regenerate index

Rewrite spec/README.md with a table: Slug | Title (per language) | Status | Last updated.

  • Status from the Status: line in the canonical file header; default draft.
  • Last updated from git log -1 --format=%cs -- <canonical file>; untracked → unversioned.
  • Never invent values—anything unreadable becomes unknown.

Coverage / duplicate check

Standalone or as step 2 of Create:

  1. Extract salient nouns/verbs from the requirement.
  2. Grep across canonical files under spec/.
  3. Read every canonical file with more than one keyword hit; assess semantic overlap, not keyword identity.
  4. Respond in user language: fully covered / partially (with gap) / no overlap.

Hard rules

  • Canonical and translations are always created and updated together.
  • After any operation: translations are in sync with canonical—no drift.
  • Slugs are ASCII kebab-case and never change silently.
  • Never modify spec/.spec-config.yml without telling the user.
  • Never invent Status, dates, or requirement content.

Sources

  • Skill file: skills/spec/SKILL.md
  • Template: skills/spec/templates/spec.template.md