electronx/wiredkits-free / skills/write-claude-md
write-claude-md
UnverifiedWrite 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.mdand any nestedCLAUDE.mdfiles if present. You are improving them, not starting over. - Read
README.md,CONTRIBUTING.md, and anyAGENTS.md,.cursorrulesor.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.
- Stack and layout. Languages, frameworks, package manager (look at lockfiles), monorepo tool, the top-level folders that matter.
- Commands. Install, dev server, build, test (all and a single file), lint, format, typecheck, migrations. Take them from
package.jsonscripts,Makefile,justfile,pyproject.toml,Cargo.toml, CI workflow files. Prefer what CI runs. - Conventions that are enforced. Linter and formatter configs, commit message rules (commitlint, PR templates), branch naming, required checks in CI.
- 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.
- 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, notnpm"), 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.mdin 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |