Spec Best Practices

Spec authoring conventions for naming, placement, structure, and lifecycle. Use when creating, reviewing, or updating SPEC.md files, running /specout, or entering the ADF SPEC gate.

223 stars 42 forksAI, LLMs & Agents

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add NeverSight/learn-skills.dev --skill spec-best-practices
Manual install
git clone --depth 1 https://github.com/NeverSight/learn-skills.dev.git /tmp/learn-skills.dev
mkdir -p ~/.claude/skills
cp -r /tmp/learn-skills.dev/data/skills-md/0xbigboss/claude-code/spec-best-practices ~/.claude/skills/spec-best-practices

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

## When to activate

Engage when:
- Creating a new spec (greenfield or retroactive)
- Reviewing or updating an existing `SPEC.md`
- Entering the ADF `SPEC` gate
- Running `/specout`
- An agent proposes a spec file with the wrong name or location

## Naming

Always `SPEC.md`. No exceptions for the primary spec file.

- Not `feature.spec.md`, not `thing-spec.md`, not `SPEC-feature.md`
- The file name is always exactly `SPEC.md`

Supporting documents linked from a `SPEC.md` TOC may use descriptive names (e.g., `commands.spec.md`, `config-and-state.spec.md`), but only when the root or package `SPEC.md` exists and links to them.

## Placement

Specs are colocated with the code they describe.

### Standard layout

```
repo/
  SPEC.md                    # root spec: project-level scope
  apps/foo/SPEC.md           # app-level spec
  packages/bar/SPEC.md       # package-level spec
  src/lib/module/SPEC.md     # module-level spec (non-monorepo)
```

### Rules

- Root `SPEC.md` covers the project/repo scope: problem, solution, domain model, cross-cutting requirements.
- Package/app/module `SPEC.md` files cover the behavior of that unit.
- Avoid `spec/`, `docs/specs/`, and `docs/plans/` directories by default. Prefer colocated `SPEC.md` files and adjacent supporting docs.
- Plan documents are ephemeral. If a plan captures durable decisions, absorb them into the relevant `SPEC.md` and delete the plan doc.

### When a spec gets long
Read the full skill on GitHub

Details

Skill name
spec-best-practices
Path
data/skills-md/0xbigboss/claude-code/spec-best-practices/SKILL.md
Repo updated
18 November 2026

FAQ

What does the Spec Best Practices skill do?

Spec authoring conventions for naming, placement, structure, and lifecycle. Use when creating, reviewing, or updating SPEC.md files, running /specout, or entering the ADF SPEC gate.

How do I install the Spec Best Practices skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add NeverSight/learn-skills.dev --skill spec-best-practices. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Spec Best Practices popular?

It lives in NeverSight/learn-skills.dev, which has 223 GitHub stars and 42 forks.

Related skills

Council

223

NeverSight/learn-skills.dev

Convene the Council of High Intelligence — multi-persona deliberation with historical thinkers for deeper analysis of complex problems.

Other42

Megaeth Developer

223

NeverSight/learn-skills.dev

End-to-end MegaETH development playbook (Feb 2026). Covers wallet operations, token swaps (Kyber Network), eth_sendRawTransactionSync (EIP-7966) for instant receipts, JSON-RPC batching, real-time mini-block subscriptions, storage-aware contract patterns (Solady RedBlackTreeLib), MegaEVM gas model, WebSocket keepalive, bridging from Ethereum, and debugging with mega-evme. Use when building on MegaETH, managing wallets, sending transactions, or deploying contracts.

Software Development42

Openclaw Stock Skill

223

NeverSight/learn-skills.dev

使用 data.diemeng.chat 提供的接口查询股票日线、分钟线、财务指标等数据,支持 A 股等市场。

Finance & Crypto42

Structural Search

223

NeverSight/learn-skills.dev

Search code by AST structure using ast-grep. Find semantic patterns like function calls, imports, class definitions instead of text patterns. Triggers on: find all calls to X, search for pattern, refactor usages, find where function is used, structural search, ast-grep, sg.

AI, LLMs & Agents42

Spawn

223

NeverSight/learn-skills.dev

Generate PhD-level expert agent prompts for Claude Code. Creates comprehensive 500-1000 line agents with detailed patterns, code examples, and best practices. Triggers on: spawn agent, create agent, generate expert, new agent, agent genesis.

AI, LLMs & Agents42

Tamagui Best Practices

223

NeverSight/learn-skills.dev

Provides Tamagui patterns for config v4, compiler optimization, styled context, and cross-platform styling. Must use when working with Tamagui projects (tamagui.config.ts, @tamagui imports).

AI, LLMs & Agents42

Browse the most popular Claude skills, all ai, llms & agents skills, or write your own with the skills generator.