Skip to content

electronx/wiredkits-free / skills/write-claude-md

write-claude-md

Unverified

Write or tighten a CLAUDE.md for the current repo from what the code actually does. Use when asked to "write a CLAUDE.md", "set up Claude for this repo", "improve our CLAUDE.md", or when Claude keeps getting the same project conventions wrong.

Write a CLAUDE.md

A good CLAUDE.md is short and holds only what Claude can't work out quickly by reading the code: how to build and test, the rules the team actually enforces, and the traps. Every line costs context on every request, so a 60-line file that is all true beats a 300-line file that restates the README.

1. Check what exists

  • Read CLAUDE.md, .claude/CLAUDE.md and any nested CLAUDE.md files if present. You are improving them, not starting over.
  • Read README.md, CONTRIBUTING.md, and any AGENTS.md, .cursorrules or .github/copilot-instructions.md. Reuse what is still true.

2. Learn the project from the code, not from guesses

Find each of these and note the exact command or path. Skip any you can't confirm.

  1. Stack and layout. Languages, frameworks, package manager (look at lockfiles), monorepo tool, the top-level folders that matter.
  2. Commands. Install, dev server, build, test (all and a single file), lint, format, typecheck, migrations. Take them from package.json scripts, Makefile, justfile, pyproject.toml, Cargo.toml, CI workflow files. Prefer what CI runs.
  3. Conventions that are enforced. Linter and formatter configs, commit message rules (commitlint, PR templates), branch naming, required checks in CI.
  4. Conventions that are only habits. Read 3 to 5 recent, typical files in the main source folder and the tests next to them. Note naming, error handling, how modules are structured, test style and fixtures. Only keep a habit if you saw it at least three times.
  5. Traps. Generated files that must not be edited by hand, env vars needed to run anything, slow or flaky test suites, services that must be running, folders that look dead but aren't. Search for DO NOT EDIT, generated, .env.example, and TODO/FIXME comments that warn about something.

Run the test and lint commands once if they are cheap and safe, so you know they work as written. Never run deploy, release or migration commands against shared environments.

3. Write it

Use this shape and drop any section that would be empty:

# <Project name>

<One or two sentences: what this is and who uses it.>

## Commands
- Install: `...`
- Dev: `...`
- Test all: `...`  Single file: `...`
- Lint / format / typecheck: `...`

## Layout
- `src/api/` HTTP handlers; business logic lives in `src/core/`.
- ...

## Rules
- <Rule stated as an instruction, with the reason when it isn't obvious.>
- ...

## Watch out
- `src/gen/` is generated by `make gen`; edit the `.proto` files instead.
- ...

Writing rules:

  • Write instructions ("Use pnpm, not npm"), not descriptions ("The project uses pnpm").
  • One fact per line. No marketing, no history, no praise of the codebase.
  • Don't repeat what a linter already enforces, and don't paste config files.
  • Don't invent rules. If you think something should be a rule but the code doesn't follow it yet, put it under Suggestions in your reply, not in the file.
  • Keep it under about 80 lines. If a part of the repo has many rules of its own, put them in a nested CLAUDE.md in that folder instead.

4. Hand it over

Show the full file (or the diff, if one existed) and then, in at most five lines:

  • Commands you ran and whether they passed.
  • Anything you could not confirm and left out.
  • Suggestions for rules the team might want to adopt.

Write the file only after showing it, unless the user already asked you to just write it.

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall