/generate-claudemd

name: generate-claudemd
description: "Generate project-specific CLAUDE.md from repo analysis."
user-invocable: false
command: /generate-claudemd
allowed-tools:
  - Read
  - Write
  - Bash
  - Grep
  - Glob
  - Skill
routing:
  triggers:
    - generate claude.md
    - create claude.md
    - init claude.md
    - bootstrap claude.md
    - make claude.md
  pairs_with:
    - go-patterns
    - codebase-overview
  complexity: Medium
  category: documentation

Generate CLAUDE.md Skill

Produce a project-specific CLAUDE.md through a 4-phase pipeline: SCAN repo facts, DETECT domain enrichment, GENERATE from template, VALIDATE output. The goal is a CLAUDE.md that makes new Claude sessions immediately productive by documenting only verified, project-specific facts.

This skill generates new CLAUDE.md files. It cannot improve an existing one (use `claude-md-improver` for that), cannot document private dependencies or encrypted configs it cannot read, cannot infer runtime behavior from static files, and cannot replace deep domain expertise — enrichment patterns are templates, not knowledge.

This skill does not use `context: fork` because it requires interactive user gates (confirmation when CLAUDE.md already exists, review of generated output), which a forked context would bypass.

Reference Loading Table

| Signal | Load These Files | Why | |---|---|---| | drafting CLAUDE.md sections in Phase 3 | `CLAUDEMD_TEMPLATE.md` | Loads detailed guidance from `CLAUDEMD_TEMPLATE.md`. | | example-driven tasks, errors | `examples-and-errors.md` | Loads detailed guidance from `examples-and-errors.md`. |

Instructions

Execute all phases sequentially. Verify each gate before advancing. Load the template from `${CLAUDE_SKILL_DIR}/references/CLAUDEMD_TEMPLATE.md` before Phase 3.

On explicit user request, two optional modes are available:

• **Subdirectory CLAUDE.md**: Generate per-package CLAUDE.md files for monorepos.
• **Minimal Mode** ("minimal claude.md"): Only 3 sections — Overview, Commands, Architecture.

> See `references/examples-and-errors.md` for worked examples by language and the complete language indicator table.

Phase 1: SCAN

**Goal**: Gather facts about the repository — language, build system, directory structure, test patterns, config approach.

**Step 1: Check for existing CLAUDE.md**

ls -la CLAUDE.md .claude/CLAUDE.md 2>/dev/null

If a CLAUDE.md already exists, write output to `CLAUDE.md.generated` and show a diff, because overwriting a hand-tuned CLAUDE.md destroys work. Inform the user: "CLAUDE.md already exists. Output will be written to CLAUDE.md.generated so you can compare." Continue with all phases — the generated file is still useful for comparison.

If no CLAUDE.md exists, set output path to `CLAUDE.md`.

**Step 2: Detect language and framework**

Check root directory for language indicators (see `references/examples-and-errors.md` for the full indicator table).

Read the detected config file to extract: project name, dependencies, language version. Do not assume standard language patterns apply — read actual source files before writing any section, because conventions vary even within the same language ecosystem.

For Go projects:

head -5 go.mod

For Node.js projects:

cat package.json | head -30

**Step 3: Parse build system**

Parse the Makefile (or equivalent) for actual build targets rather than guessing commands, because the Makefile IS the source of truth for build commands in most repos and may wrap tools with flags, coverage, or race detection that raw invocations would miss.

ls Makefile makefile GNUmakefile 2>/dev/null
grep -E '^[a-zA-Z_-]+:' Makefile 2>/dev/null | head -20

Also check for: `package.json` scripts section, `Taskfile.yml`, `justfile`, CI config (`.github/workflows/`, `.gitlab-ci.yml`).

Record: build command, test command, lint command, "check everything" command. If no build system is found at all, document the gap rather than inventing commands.

**Step 4: Map directory structure**

ls -d */ 2>/dev/null
# Go projects:
ls internal/ cmd/ pkg/ 2>/dev/null

Categorize directories by role (source, test, config, docs, build, vendor).

**Step 5: Find test patterns**

ls *_test.go 2>/dev/null | head -5          # Go
ls *.test.ts *.test.js 2>/dev/null | head -5 # Node.js
ls test_*.py *_test.py 2>/dev/null | head -5 # Python

Read 1-2 representative test files to identify: test framework, assertion library, mocking approach, naming conventions.

**Step 6: Detect configuration approach**

ls .env.example .env.sample 2>/dev/null
ls config.yaml config.json *.toml *.ini 2>/dev/null
grep -r 'os.Getenv\|flag\.\|viper\.\|envconfig' --include='*.go' -l 2>/dev/null | head -5

**Step 7: Detect code style tooling**

ls .golangci.yml .eslintrc* .prettierrc* .flake8 pyproject.toml .editorconfig 2>/dev/null

If a linter config exists, read it to extract key rules.

**Step 8: Check for license headers**

grep -r 'SPDX-License-Identifier' --include='*.go' --include='*.py' --include='*.ts' -l 2>/dev/null | head -3

If found, note the license type and header convention.

**GATE**: Language detected. Build targets identified. Directory structure mapped. Test patterns found (or noted as absent). Config approach documented. Proceed ONLY when gate passes.

---

Phase 2: DETECT

**Goal**: Identify domain-specific enrichment sources based on repo characteristics. Auto-detect the repo domain and load domain-specific patterns (sapcc Go conventions, OpenStack patterns, etc.) because generic language knowledge is insufficient for project-specific CLAUDE.md generation.

**Step 1: Check for sapcc domain (Go repos)**

If Go project detected:

grep -i 'sapcc\|sap-' go.mod 2>/dev/null
grep -r 'github.com/sapcc' --include='*.go' -l 2>/dev/null | head -5

If sapcc imports found, load enrichment from `go-patterns` skill patterns:

• Anti-over-engineering principles