Scripts

The kit includes utility scripts in scripts/. These are not hooks — they're standalone tools you run manually.

doctor.sh

Usage: ./scripts/doctor.sh

Health check for your Claude Code Kit installation. Verifies:

• Core files exist (CLAUDE.md, CODEBASE_MAP.md, agent_docs/, tasks/)
• Hook files are executable
• settings.json is valid JSON
• Hooks in .claude/hooks/ are referenced in settings.json (detects orphans)
• CODEBASE_MAP.md has no unfilled placeholders
• Agents and skills directories exist with expected counts
• Skills pass validation (if validate-skills.sh is available)

./scripts/doctor.sh

  Claude Code Kit — Doctor
  ========================

  Core files
  ----------
  ✓ CLAUDE.md exists
  ✓ CODEBASE_MAP.md exists
  ✓ agent_docs/ exists
  ✓ tasks/ exists

  Hooks
  -----
  ✓ .claude/hooks/ exists
  ✓ protect-files.sh is executable
  ✓ branch-protect.sh is executable
  ...

  Summary
  -------
  18 passed, 0 failed, 1 warnings

validate.sh

Usage: ./scripts/validate.sh [path/to/CODEBASE_MAP.md]

Checks CODEBASE_MAP.md for unfilled placeholders and empty sections. Detects patterns like [command], [module], ..., and HTML comments.

./scripts/validate.sh

validate-skills.sh

Usage: ./scripts/validate-skills.sh [path/to/skills]

Validates skill files for completeness and quality:

./scripts/validate-skills.sh

statusline.sh

Usage: Configure in .claude/settings.json

Status line script that shows model name, git branch, context usage (progress bar), and session cost.

{
  "statusLine": {
    "command": "./scripts/statusline.sh"
  }
}

Reads JSON from stdin with fields: model, contextWindow, contextUsed, costUSD, sessionId.

Output example:

opus-4 | feat/my-branch | ████████░░ 80% | $0.42

convert.sh

Usage: ./scripts/convert.sh

Multi-tool export script for converting agent definitions to different formats.

gen-skill-docs.sh

Usage: ./scripts/gen-skill-docs.sh [--out <dir>] [--agents] [--dry-run]

Generates web-ready Fumadocs MDX documentation from SKILL.md files. Reads each .claude/skills/*/SKILL.md, strips YAML frontmatter, and produces a Fumadocs-compatible MDX file. With --agents, also generates agent docs from .claude/agents/*.md. This prevents drift between kit skills/agents and web documentation.

# Generate all skill docs to default output directory
./scripts/gen-skill-docs.sh

# Generate skill + agent docs
./scripts/gen-skill-docs.sh --agents

# Preview without writing
./scripts/gen-skill-docs.sh --dry-run

# Custom output directory
./scripts/gen-skill-docs.sh --out ./docs/content

build-skills.sh

Usage: ./scripts/build-skills.sh [--list | --dry-run | <name>]

Builds SKILL.md files from .tmpl templates by replacing {{PLACEHOLDER}} tags with content from shared blocks.

# List available blocks and templates
./scripts/build-skills.sh --list

# Preview what would be generated
./scripts/build-skills.sh --dry-run

# Build all templates
./scripts/build-skills.sh

# Build a single skill
./scripts/build-skills.sh code-quality-audit

Templates live in .claude/skills/_templates/*.tmpl and shared blocks in .claude/skills/_shared/blocks/*.md. The block filename maps to the placeholder: preamble.md becomes {{PREAMBLE}}, scope-rules.md becomes {{SCOPE_RULES}}.

gen-agents-md.sh

Usage: ./scripts/gen-agents-md.sh [path]

Generates a cross-tool AGENTS.md from your project sources (CLAUDE.md, CODEBASE_MAP.md, agent_docs). AGENTS.md is a one-way derived output — the source of truth stays CLAUDE.md. Also available as npx @tansuasici/claude-code-kit generate agents-md.

sync-manifest.sh

Usage: ./scripts/sync-manifest.sh [--check]

Regenerates .kit-manifest, the list of kit-managed files that --upgrade uses to know what it owns. --check exits non-zero if the manifest is stale — CI runs it on every PR so the manifest can't drift from the tree.

run-bench.sh

Usage: ./scripts/run-bench.sh [--scenario s01 | --filter <name> | --verbose | --json]

Runs KitBench — every hook scenario in bench/scenarios/*.json (25 today) in a fresh temp dir, no LLM, no network. Exit 0 all pass, 1 one or more fail, 2 runner error. CI runs it on every PR.

lesson-graph.sh

Usage: ./scripts/lesson-graph.sh

Regenerates the auto-managed sections of tasks/lessons/_index.md (Top Rules, Active Rules By Topic, Recently Added, Superseded) from each lesson's applies_to / supersedes frontmatter. Deterministic — never edit those sections by hand.

lesson-resurface.sh

Usage: ./scripts/lesson-resurface.sh "<task summary>"

Backs the /lesson-resurface skill. Returns ranked pointers (paths only, never bodies) to archived or superseded lessons whose topic tags match the task, so dormant context can be recovered without bloating session boot.

migrate-lessons.sh

Usage: ./scripts/migrate-lessons.sh

One-time migration from the legacy single-file tasks/lessons.md to the current per-file tasks/lessons/ structure (with frontmatter + _index.md). Only needed when upgrading an installation that predates the per-file format.

note.sh

Usage: ./scripts/note.sh <finding|decision|summary> "<text>"

Backs the /note skill. Appends a validated, timestamped line to .hook-state/session-journal.md for across-compaction memory; journal-fold.sh folds findings/decisions into the session handoff at SessionEnd.