CLAUDE.md Examples

Why it's notable: A persona file that is actually a decision procedure: the 'lazy senior dev' framing resolves into a concrete 7-rung ladder (YAGNI → reuse → stdlib → one line → minimal code) plus an explicit list of what NOT to be lazy about. It turns a vibe into checkable behavior.

Why it's notable: A masterclass in structuring a multi-skill agent system in one file: three named flows (Setup / Decide / Deliver), a skill catalog, and a full 'Definition of Ready' + label state-machine for running the agent unattended over an issue tracker. Shows how to encode an entire operating model, not just rules.

Why it's notable: The clearest way to express code conventions to an agent: every rule (inline single-use vars, no unnecessary destructuring, early returns over else, snake_case Drizzle columns) is a tight Good/Bad code pair, not prose. The Knip section shows how to encode a tool's failure modes and the exact fix for each.

Why it's notable: A rare example that spends most of its length defining boundaries: what the skill must exclude (architecture opinions, formatting, tool instructions) and a suggest-vs-require rubric ('consider' for optimizations, 'always/never' only for correctness). A strong template for keeping a domain skill focused and non-opinionated.

Why it's notable: Organizes guidance around a dedicated Anti-Patterns section — SQL injection, secrets, resource cleanup, missing compatibility_date — each a NEVER/ALWAYS code pair. Also shows how to flag a non-obvious repo fact (this repo uses jujutsu, not git) so the agent doesn't reach for the wrong tool.

Why it's notable: A compact, well-annotated map of a monorepo that ships parallel Claude Code and Codex editions from one source tree. Cleanly separates analysis skills (return findings) from workflow skills (act on them), and points at the edition-specific AGENTS.md rather than duplicating rules.

Why it's notable: Nails the single most common agent footgun in a build-step repo: a load-bearing 'edit src/, NEVER edit plugins/' invariant, spelled out with the build note that generated diffs are expected and must be staged. The Session Resilience section (commit per logical unit, rate limits can kill a session) is broadly transferable.

Why it's notable: A fully worked example of using CLAUDE.md as the agent's persistent identity and voice spec — Core Truths, Vibe, emoji budget, boundaries — treating the file as memory reloaded every session. Useful as a reference for the persona/voice half of an agent config, distinct from the engineering rules other examples cover.

Why it's notable: Demonstrates the pointer pattern done well: AGENTS.md declares CLAUDE.md the single source of truth and links the architecture/contributing docs, then still carries the handful of essentials (minimal-intrusion, YAGNI, invariants, verify commands) an agent needs before opening anything else. Includes a crisp AI-assisted vs AI-authored attribution rule.

Why it's notable: An unusually disciplined content policy for skill authors: add a use case only when it beats fetching the docs, put 'when to use' guidance in exactly two places and nowhere else, and never commit code that will go stale. The reasoning ('a reference body is read only after the agent chose to open it') is a portable mental model.

Why it's notable: The most actionable take on SKILL.md frontmatter: the exact allowed fields, the lowercase-hyphen name rule, and a validation-error → fix table so the agent can self-correct. A clean model for encoding a spec's constraints plus its common failure modes in one place.

Why it's notable: Frames a markdown-authoring repo as red-green-refactor with the validator as the test gate, and gives an explicit 'Definition of Done — run before every commit' block of exact commands. The Gotchas section (generated README tables, description length limit) captures the tribal knowledge that usually lives only in reviewers' heads.

Why it's notable: A model of restraint: the file opens by stating it is intentionally short, links the canonical AGENTS.md / instructions / architecture docs, and lists only the few ground rules that must be seen first. It even encodes the conflict-resolution rule — trust the linked source and delete the duplicate here — which keeps the file from drifting.

Why it's notable: A complete, transferable playbook for a skills repository: the directory contract, the SKILL.md frontmatter, the token/line budget, the 'body is written for Claude, not end users' rule, and the exact marketplace.json edit needed to register a new skill. Concrete about the steps that are easy to forget.

Why it's notable: Shows the pragmatic way to serve multiple agents from one file — CLAUDE.md is a symlink to AGENTS.md, noted up front — and routes all commands through a mise task runner so the same 'run check and build before completing' contract holds in CI. Good reference for the generated-file layout (SKILL.md → AGENTS.md → CLAUDE.md).

Why it's notable: One of the most-copied skill-authoring references: a full SKILL.md skeleton (How It Works / Usage / Output / Present Results / Troubleshooting), a context-efficiency section explaining progressive disclosure and the 500-line budget, and hard script requirements (set -e, JSON to stdout, status to stderr).

Why it's notable: Distills skill authoring to a numbered quick checklist plus a 'What Makes a Good Skill' rubric (concise, third-person description, what+when, one-level-deep references, no redundancy). Pairs well with the longer Vercel template when you want the short version of the same standard.

Why it's notable: A tight, transferable style guide for a TypeScript MCP server: ESM with .js import extensions, zod for tool-input validation, and the non-obvious '.nullable() instead of .optional() for MCP tool params (gpt-5 compatibility)' rule — exactly the kind of cross-model gotcha worth encoding once so the agent doesn't rediscover it.