shipit: Skill for Claude Code

Feature Docs Navigator

ShipIt has feature docs in docs/NNN-feature-name/plan.md. Each describes how a feature was designed and implemented. Most tasks don't need these — the architecture skills cover cross-cutting patterns. Load a feature doc only when you need implementation details for a specific feature.

How to use

1. Run the index script to get the current list of docs with their status and title:

   bash .agents/skills/docs-navigator/index.sh
   

2. Find the relevant doc(s) from the output
3. Read its plan.md for design details
4. Check checklist.md if it exists — it tracks remaining work

Status key

• done — implemented and shipped
• in-progress — actively being worked on
• planned — designed but not yet started
• paused — designed but not currently scheduled

Filtering

The index script accepts an optional filter argument to narrow results:

# Show only planned/in-progress docs
bash .agents/skills/docs-navigator/index.sh active

# Show only docs matching a keyword
bash .agents/skills/docs-navigator/index.sh git
bash .agents/skills/docs-navigator/index.sh deploy

Writing docs: folder layout

docs/
  NNN-feature-name/
    requirements.md — What the feature must do, in the human's terms (required for new features)
    plan.md        — How the feature works, key files, patterns
    checklist.md   — Remaining work items or tracking notes
    mockup.html    — Optional UI prototype committed as reference (or mockup.svg / mocks/)

Features are numbered by creation order. Create docs/NNN-new-feature/ for a new one.

docs/NNN-feature/ is this repo's convention, not the docs list's filter. The scan (markdown.ts → findMarkdownFiles) walks the whole workspace and surfaces every .md file — README.md, RELEASING.md, src/server/shipit-docs/*.md, anything nested. The NNN- prefix and the presence of plan.md / checklist.md / an issue: pointer only decide Tracked-vs-Other grouping and newest-first ordering. So treat any markdown you write as user-visible; don't leave scratch notes in .md.