skills.rest
surfingalien
surfingalienCOMMUNITY
Explore all skills by this author →
GitHub

spec

Creates, amends, and backprops bugs into a SPEC.md project specification file.

1|Updated May 6, 2026
Search Tags:#project management#documentation#markdown#specification#spec#bug tracking#invariants
One-click install
npx skills add https://github.com/surfingalien/FinSurfing --skill spec-surfingalien
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: spec
Source: https://github.com/surfingalien/FinSurfing/tree/main/.claude/skills/ck%3Aspec
Command: npx skills add https://github.com/surfingalien/FinSurfing --skill spec-surfingalien

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Keeping a project specification accurate as code evolves is hard: specs drift from implementation, bugs get fixed without updating invariants, and ad-hoc edits break document structure. This Skill makes SPEC.md the single source of truth by acting as its sole mutator, enforcing a strict caveman-encoded format with numbered sections. ## Core Features & Use Cases - Four dispatch modes: NEW (idea to spec), DISTILL (reverse-engineer a spec from existing code), BACKPROP (record bugs into section B and derive new invariants in section V), and AMEND (targeted edits to named sections like §V.3 or §T). - Structured spec format: Maintains sections §G (goal), §C (constraints), §I (interfaces), §V (invariants), §T (task pipe table), and §B (bug log) with monotonic numbering that is never reused. - Use Case: After fixing a recurring authentication bug, invoke the skill with "bug: session token not refreshed" to append a §B row, draft a new invariant in §V, and update affected §T tasks — all shown as a diff before applying. ## Quick Start Ask the assistant to write the spec for your project idea, or say "bug: <description>" to backprop a bug into the existing SPEC.md.

Frequently Asked Questions about spec

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a project spec from an idea?▼

Invoke the skill with a description of your idea and no existing SPEC.md. It extracts a one-line goal, constraints, interfaces, and initial invariants, then breaks the goal into ordered tasks in a pipe table before writing SPEC.md for your review.

How to generate a spec from an existing codebase?▼

Use the distill mode by including "from-code" in your request when no SPEC.md exists. The skill walks the repo, infers the goal from README and entry points, enumerates public APIs, derives invariants from tests, and flags uncertain items with a question mark.

What is bug backpropagation in a spec workflow?▼

Backprop records a bug by appending a row to section B with its root cause, then optionally drafts a new invariant in section V that would catch recurrence. If the fix changes behavior, affected task rows in section T are updated too.

Can I edit only one section of SPEC.md?▼

Yes, use amend mode with a target like "amend §V.3" or "amend §T". The skill shows the current section content, asks what changes you want, writes them, and shows a diff without touching unnamed sections.

What are the limitations of this spec skill?▼

It does not spawn sub-agents, build dashboards, or keep state files beyond SPEC.md itself, and it never auto-triggers a build after writing the spec. All writes follow the caveman format defined in FORMAT.md, which must exist at repo root.

Related Skills

Explore More Software Engineering Skills→
davidYichengWeidavidYichengWei
159

workflow-requirements-clarification

Extract codebase context and user needs into a structured requirements spec.

Community
Advanced
brandon-setegnbrandon-setegn

openspec-apply-change

Implement OpenSpec change tasks by reading status and executing pending work.

Community
Advanced
thrawn01thrawn01
11

invariant-test

Derive mutation-validated surface tests from service invariants.

Community
Advanced
joestumpjoestump
30

spec

Create and maintain paired OpenSpec specification and design documents.

Community
Advanced