creating-claude-md

An Agent Skill for generating a lean, high-signal CLAUDE.md (or AGENTS.md) for a repository from scratch.

Works with Claude Code, Codex, and any other coding agent that supports the SKILL.md format.

What it does

Bootstraps project memory for a repo by combining:

1. An autonomous repo scan — manifests, structure, linter configs, git history, existing docs, configured MCPs.
2. A focused 6-question interview — the judgment content only the user can supply (WHY, gotchas, out-of-scope, approval gates, testing philosophy, external docs like Confluence pages).

The output is a CLAUDE.md under 80 lines (120 hard cap) where every line earns its place. If a line wouldn’t prevent a specific mistake, the skill deletes it.

When to use

• Repo has no CLAUDE.md and you want one.
• Existing CLAUDE.md is unsalvageable and you want a clean rewrite.
• You’re setting up a repo for an agent for the first time.

Not for auditing or incrementally improving an existing CLAUDE.md — that’s a separate concern.

Install

Claude Code

Clone into the skills directory:

git clone https://github.com/sruthik27/creating-claude-md.git ~/.claude/skills/creating-claude-md

Then in any repo, ask Claude Code to “create a CLAUDE.md” or “bootstrap project memory” and the skill will trigger.

Codex / other agents

Point your agent at the SKILL.md file. The format is plain Markdown with YAML frontmatter — most agent runtimes that support skills accept it as-is.

Key design choices

• 80-line target, 120 hard cap. Bloat causes harnesses to down-weight every instruction in the file, not just the tail. The cap is a forcing function.
• Imperative rules, paired with positive alternatives. “Never force-push; rebase locally then push normally” beats “Never force-push” alone.
• No content that linters already enforce. Indentation, quotes, import order, etc. go in .eslintrc / biome.json / ruff.toml, not CLAUDE.md.
• External docs by reference, never by paste. Confluence/Notion URLs + purpose + read/update policy. CLAUDE.md is not a cache.
• Aux files only when the root exceeds 80 lines. No speculative scaffolding.

License

MIT