How do I install the Spec skill?

Run npx skillmds add om-scogo/spec 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.

This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Spec?

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.

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

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

Spec by om-scogo — Agent Skill

Name: Spec
Rating: 4.2 (5 reviews)
Author: om-scogo

Spec

Create, amend, or backprop bugs into SPEC.md at repo root. Sole mutator of the project spec. Triggers when the user asks to write a spec, start a new spec, distill a spec from existing code, add invariants, amend sections (§G, §C, §I, §V, §T, §B), or record a bug via backprop. Common phrasings: "write the spec for...", "new spec", "bug: ...", "amend §V.3", "distill spec from code", "spec this idea". Reads and follows FORMAT.md for the caveman encoding rules and pipe-table shape of §T and §B.

om-scogo 97bcf2d 4 files · 10.7 KB Updated Sep 9, 2026 0 repo stars

File contents

spec — spec mutator

Read FORMAT.md at repo root if not already loaded. Caveman skill applies to all writes here.

DISPATCH

Inspect user request and project state:

No SPEC.md at repo root AND args describe idea → NEW
No SPEC.md AND from-code in args → DISTILL
SPEC.md exists AND args start bug: → BACKPROP
SPEC.md exists AND args start amend → AMEND
SPEC.md exists, no args → ask user which mode

INPUTS — spec is the sole mutator

The other verbs produce material; spec writes it. Ingest their handoff blocks into the right section, show a diff, write on OK:

grill → sharpened §G + §C
research → §R rows (add the §R section if absent)
review → drafted §V lines + the risk verdict
deepen → §I/§V/§T amendments

⊥ rewrite a section the handoff did not name. Sectioned ownership (see FORMAT.md).

NEW — idea → spec

Input: user idea. If it arrived fuzzy, prefer running grill first.

Steps:

Extract goal (1 line, caveman). → §G.
List constraints user stated or implied. → §C.
List external surfaces user named. → §I.
§R only if research ran — else omit the section (right-size).
Propose initial invariants. → §V (numbered V1…).
Break goal into ordered tasks. → §T pipe table, all status ., ids T1…
§B section with header row only (id|date|cause|fix).

Write to SPEC.md. Show user full file. Ask: "spec OK? /review if high-blast-radius, else /build."

DISTILL — code → spec

Walk repo. Produce §G (infer from README/package.json/main entry), §C (infer from stack), §I (enumerate public APIs/CLIs/configs), §V (derive from tests and assertions), §T (one task per known TODO or missing test), §B (empty).

Caveman everywhere. Flag uncertain items with ? in text so user can confirm.

BACKPROP — bug → §B + §V

Input: bug: <description>.

Steps:

Parse bug description.
Find root cause (read relevant code).
Decide: would a new invariant catch recurrence? If yes → draft V<next>.
Append §B row: B<next>|<date>|<cause>|V<N>.
Append new invariant to §V.
If fix also changes behavior → add/update §T rows.
Show diff. Apply only on user OK.

Rule: every bug gets a §B entry. Invariant optional but preferred.

AMEND — targeted edit

Input: amend §V.3 or amend §T etc.

Read that section. Show current. Ask user what changes. Write. Show diff.

Never silently rewrite sections user did not name.

OUTPUT RULES

Caveman format per FORMAT.md.
Preserve identifiers, paths, code verbatim.
Numbering monotonic — never reuse §V.N or §B.N.
§T row cites column ! list §V/§I deps: T5|.|impl auth mw|V2,I.api.

NON-GOALS

No sub-agents. Main thread writes.
No dashboards, no logs, no state files beyond SPEC.md itself.
No auto-build after spec. User invokes build explicitly.

---name: specdescription: Create, amend, or backprop bugs into SPEC.md at repo root. Sole mutator of the project spec. Triggers when the user asks to write a spec, start a new spec, distill a spec from existing code, add invariants, amend sections (§G, §C, §I, §V, §T, §B), or record a bug via backprop. Common phrasings: "write the spec for...", "new spec", "bug: ...", "amend §V.3", "distill spec from code", "spec this idea". Reads and follows FORMAT.md for the caveman encoding rules and pipe-table shape of §T and §B.--- # spec — spec mutator Read `FORMAT.md` at repo root if not already loaded. Caveman skill applies to all writes here. ## DISPATCH Inspect user request and project state: 1. No `SPEC.md` at repo root AND args describe idea → **NEW** 2. No `SPEC.md` AND `from-code` in args → **DISTILL** 3. `SPEC.md` exists AND args start `bug:` → **BACKPROP** 4. `SPEC.md` exists AND args start `amend` → **AMEND** 5. `SPEC.md` exists, no args → ask user which mode ## INPUTS — spec is the sole mutator The other verbs produce material; spec writes it. Ingest their handoff blocks into the right section, show a diff, write on OK: - **grill** → sharpened §G + §C - **research** → §R rows (add the §R section if absent) - **review** → drafted §V lines + the risk verdict - **deepen** → §I/§V/§T amendments ⊥ rewrite a section the handoff did not name. Sectioned ownership (see FORMAT.md). ## NEW — idea → spec Input: user idea. If it arrived fuzzy, prefer running **grill** first. Steps: 1. Extract goal (1 line, caveman). → §G. 2. List constraints user stated or implied. → §C. 3. List external surfaces user named. → §I. 4. §R only if **research** ran — else omit the section (right-size). 5. Propose initial invariants. → §V (numbered V1…). 6. Break goal into ordered tasks. → §T pipe table, all status `.`, ids T1… 7. §B section with header row only (`id|date|cause|fix`). Write to `SPEC.md`. Show user full file. Ask: "spec OK? `/review` if high-blast-radius, else `/build`." ## DISTILL — code → spec Walk repo. Produce §G (infer from README/package.json/main entry), §C (infer from stack), §I (enumerate public APIs/CLIs/configs), §V (derive from tests and assertions), §T (one task per known TODO or missing test), §B (empty). Caveman everywhere. Flag uncertain items with `?` in text so user can confirm. ## BACKPROP — bug → §B + §V Input: `bug: <description>`. Steps: 1. Parse bug description. 2. Find root cause (read relevant code). 3. Decide: would a new invariant catch recurrence? If yes → draft `V<next>`. 4. Append §B row: `B<next>|<date>|<cause>|V<N>`. 5. Append new invariant to §V. 6. If fix also changes behavior → add/update §T rows. 7. Show diff. Apply only on user OK. Rule: every bug gets a §B entry. Invariant optional but preferred. ## AMEND — targeted edit Input: `amend §V.3` or `amend §T` etc. Read that section. Show current. Ask user what changes. Write. Show diff. Never silently rewrite sections user did not name. ## OUTPUT RULES - Caveman format per `FORMAT.md`. - Preserve identifiers, paths, code verbatim. - Numbering monotonic — never reuse §V.N or §B.N. - §T row `cites` column ! list §V/§I deps: `T5|.|impl auth mw|V2,I.api`. ## NON-GOALS - No sub-agents. Main thread writes. - No dashboards, no logs, no state files beyond SPEC.md itself. - No auto-build after spec. User invokes build explicitly.

Frequently asked questions