authoring-claude-md_skill

Overview

This skill creates and maintains CLAUDE.md project memory files that capture non-obvious codebase context for AI coding agents. It focuses on actionable, high-signal guidance—architectural decisions, recurring gotchas, and project-specific conventions that agents cannot reliably infer from code alone. Use it to reduce repeated investigation and speed up agent-driven development workflows.

How this skill works

The skill inspects the codebase and existing docs, identifies gaps where agents repeatedly ask the same questions, and generates concise CLAUDE.md sections with clear instructions and links to source files. It emphasises short, pragmatic entries: what to do, why it matters, and when to consult other documentation. Entries avoid duplication, line numbers, and generic advice, and are scoped to patterns that will recur across coding sessions.

When to use it

• Creating a new CLAUDE.md for a project where agents will perform frequent code changes or automated tasks
• Adding architectural decisions or non-obvious patterns discovered during codebase exploration
• Documenting recurring debugging steps or confirmed fixes that saved investigation time
• Capturing conventions that linters or READMEs do not enforce, but agents must follow
• Linking to specialised docs (schemas, auth flows) with context on when to consult them

Best practices

• Write only non-obvious, actionable items: prefer commands and file paths over vague warnings
• Keep sections short (2–4 sections max) and use headings for quick scanning
• Link to existing documentation rather than duplicating content; state when to read it
• Avoid formatting rules, setup steps, and one-off fixes; use code comments or targeted docs instead
• Update CLAUDE.md when a recurring friction or confirmed solution appears, not for hypothetical issues

Example use cases

• Add a note explaining why raw SQL is used for reports and where queries live (/queries) to avoid misguided ORM changes
• Document a cache race workaround: always acquire lock in src/cache/lock.ts before validation
• Record token refresh flow for background jobs with file reference src/auth/refresh.py and exact function to call
• Summarise event-driven architecture decisions and point to src/events/README.md for schema details
• Capture a repeated TypeError root cause and the exact code change that resolves it