Feature-spec skill

Turn a built or planned backend feature into a single structured feature-spec.md that any AI agent or teammate can act on.

Reads a repo directly (git diff, route files, schema, OpenAPI) when available, or works from pasted code or a plain description. Produces a versioned spec covering intent, persona, screens, API surface, data changes, auth, events, and frontend impact.

Install

No global install needed — works with npx, pnpm dlx, or bunx:

npx feature-spec install
pnpm dlx feature-spec install
bunx feature-spec install

This auto-detects which agents are present in your project and installs accordingly. To target a specific agent (swap npx for pnpm dlx or bunx as preferred):

npx feature-spec install claude          # Claude Code (global ~/.claude/skills/)
npx feature-spec install claude-project  # Claude Code (project .claude/skills/)
npx feature-spec install cursor          # Cursor (.cursor/rules/)
npx feature-spec install kilocode        # Kilocode (.kilocode/rules/)
npx feature-spec install windsurf        # Windsurf (.windsurf/rules/)
npx feature-spec install agents          # Generic .agents/ folder
npx feature-spec install codex           # Codex / OpenAI (.agents/skills)
npx feature-spec install antigravity     # Antigravity (.agents/skills)
npx feature-spec install copilot         # GitHub Copilot (.agents/skills)
npx feature-spec install amp-code        # Amp Code (.amp/rules/)

Uninstall

npx feature-spec uninstall            # auto-detect and remove
npx feature-spec uninstall cursor     # remove from one platform

List supported platforms

npx feature-spec list

Usage

Once installed, invoke the skill inside your agent:

/feature-spec

Point it at what you have:

• Branch or PR — generate a spec for the refund work on this branch
• Pasted endpoints — paste your route definitions and say write this up for the frontend
• Plain description — document the invite-teammates feature I'm about to build

The skill writes a versioned spec to docs/specs/<feature-slug>.md.

What the spec covers

| Section | What it captures | |---|---| | Intent | One-line plain-English purpose — always present, even for trivial features | | Persona | Who uses it (inferred from auth + side-effects) | | Screens & states | Proposed UI surfaces and the states that matter | | API surface | Each endpoint: method, path, fields, response shape, error cases | | Auth / permissions | Role checks, scopes, who gets a 403 | | Field / data changes | New or changed columns, enums, defaults | | Events / side-effects | Emails, webhooks, jobs, denormalized fields | | Frontend impact | The "so what" — what the frontend must build, change, or handle | | Assumptions | Every inference flagged explicitly — nothing stated as fact that wasn't confirmed |

Design principles

Synthesize, don't transcribe. Swagger already dumps your API. This skill connects "there's a refund_reason column and a POST /refunds endpoint" to "the refund form needs a reason input, the order view should display it, and non-admins get a 403."

Fast path for trivial features. A plain CRUD endpoint with no new persona, screen, or permission rule gets a minimal spec — just Intent and API surface. The full PM-reasoning pass is reserved for features that carry product weight.

Honest gaps beat confident guesses. Anything inferred goes in Assumptions. Blank sections stay blank rather than being padded.

Example output

# Feature spec: refund-flow

## Intent
Lets a support admin issue a refund against an order, recording a reason.
The customer is notified afterward (see Assumptions).

## Persona
- Support admin (primary — issues the refund)
- Customer (secondary — receives confirmation, does not act)

## Screens & states
- Refund form — default, error, permission-denied
- Order detail — shows refund status and a Refund button (admin-only)

## API surface
- POST /refunds
  - Request: order_id (string, required), refund_reason (string, required), amount (number, optional)
  - Response: refund_id (string), status (enum: pending | completed | failed)
  - Error: 422 on invalid amount

## Auth / permissions
- POST /refunds requires role: admin (403 otherwise)

## Field / data changes
- refunds.refund_reason — new TEXT column (required)
- orders.status — adds "refunded" value

## Events / side-effects

## Frontend impact
- Order detail needs a Refund button, gated to admins
- Refund form needs a required reason input and must surface the 422 inline
- No optimistic UI — permission and amount checks can reject server-side

## Assumptions / open questions
- amount optional is read as "defaults to full refund" — confirm with backend
- customer confirmation assumed to be email; in-app screen unclear

License

MIT