claude-md-starter

Files (4)

• SKILL.md
• claude-md-template.md · references/
• scan-signals.md · references/
• validation-checklist.md · references/

SKILL.md (first lines)

# Claude.md Starter — Project Context Generator

Scans the repo, infers the tech stack and conventions, asks at most 3 targeted questions, and writes a populated CLAUDE.md that gives Claude full project context from session one.

## Invocation Triggers

**Explicit:**
- "create a CLAUDE.md"
- "my CLAUDE.md is blank"
- "generate project context"
- "initialize CLAUDE.md"
- "set up Claude context for this repo"
- "fill in my CLAUDE.md"
- "run the claude-md-starter skill"

**Implicit:**
- User pastes a near-empty CLAUDE.md and asks Claude to populate it
- User keeps re-explaining the same project context at the start of sessions

Run immediately when triggered — no upfront questions before scanning.

## Workflow (6 Nodes)

| Node | Role |
|---|---|
| 1 — Detect | Check if CLAUDE.md exists and measure content length |
| 2 — Scan | Read signal files from the project root (see `references/scan-signals.md`) |
| 3 — Infer | Draft all sections that can be derived from scanned signals |
| 4 — Grill-me | Ask at most 3 questions for what cannot be inferred |
| 5 — Generate | Write the full CLAUDE.md using the template in `references/claude-md-template.md` |
| 6 — Validate | Confirm required sections are present and non-placeholder |

## Node 1 — Detect

Check for CLAUDE.md at the project root.

**If not found:** Proceed directly to Node 2.

**If found and has ≤ 200 characters:** Treat as blank — proceed to Node 2.

**If found and has > 200 characters:** Run the diff-and-merge flow before writing:

1. Read the existing file
2. Complete Nodes 2–4 to produce the generated version
3. Compare section by section — for each of the 8 required sections, classify as:
   - **NEW** — exists in generated, absent or empty in existing
   - **ENHANCED** — both versions have content; generated version adds more
   - **SAME** — both versions have equivalent content
   - **CONFLICT** — both versions have different non-empty content

4. Present a diff summary table:

```
Section              | Existing | Generated | Action
---------------------|----------|-----------|-------
Project Overview     | present  | enhanced  | +additions available
Tech Stack           | absent   | new       | will add
Commands             | present  | enhanced  | +2 commands found
Architecture         | absent   | new       | will add
Code Conventions     | present  | same      | no change
Testing              | absent   | new       | will add
What NOT To Do       | absent   | new       | will add
Environment Setup    | absent   | new       | will add
```

5. Offer three options:
   - **A (Recommended)** — Keep existing content + add new and enhanced sections only (safe, additive)
   - **B** — Full replace with generated version
   - **C** — Review each conflicting section individually before writing

6. Write the chosen merge result.

## Node 2 — Scan

Read signal files using the catalog in `references/scan-signals.md`. For each file found, extract the fields it reveals. Missing files are skipped silently.

Run all reads in parallel where possible:

1. `package.json` — framework, scripts, package manager, dependencies
2. `pyproject.toml` / `requirements.txt` / `setup.py` — Python stack
3. `Cargo.toml` / `go.mod` / `pom.xml` / `build.gradle` — language
4. `Makefile` / `justfile` — named commands
5. `.github/workflows/*.yml` — CI/CD steps, deploy targets
6. `Dockerfile` / `docker-compose.yml` — runtime environment, services
7. `.eslintrc.*` / `.prettierrc.*` / `eslint.config.*` — JS/TS code style
8. `ruff.toml` / `.flake8` / `mypy.ini` — Python lint/type config
9. `jest.config.*` / `vitest.config.*` / `pytest.ini` / `conftest.py` — test framework
10. `tsconfig.json` — TypeScript settings
11. `.env.example` / `.env.sample` — required environment variables
12. `README.md` (first 40 lines only) — project description
13. Top-level directory listing — architecture pattern
14. `.gitignore` — build artifacts and generated files

## Node 3 — Infer

Using scanned data, populate as many sections as possible before asking questions:

- **Project Overview** → from README.md first paragraph; fall back to `package.json` `description` field
- **Tech Stack** → from language files + framework dependencies
- **Commands** → from `package.json` scripts, Makefile targets, workflow run steps
- **Architecture** → from top-level directory structure
- **Code Conventions** → from eslint/prettier/ruff config values
- **Testing** → from test config files and test directory location
- **What NOT To Do** → from `.gitignore` build outputs, workflow branch protection, lock files
- **Environment Setup** → from `.env.example` variable names and docker-compose services

## Node 4 — Grill-Me Intake

Ask only for what cannot be inferred. Maximum 3 questions. Skip any question whose answer is already clear from scanned files.

Present all applicable questions together in one message — never ask them across multiple turns:

> **Quick questions to finish your CLAUDE.md** (answer whichever apply):
>
> 1. What does this project do in one sentence? *(skip if README was found)*
> 2. Are there any files, directories, or systems that should never be touched or auto-modified by Claude?
> 3. Any team conventions not captured in your lint config? *(naming patterns, PR size, commit format, review process)*

## Node 5 — Generate

From Infrasity-Labs/dev-gtm-claude-skills, MIT.

More from Infrasity-Labs/dev-gtm-claude-skills