claude-md-authoring_skill

Overview

This skill creates and maintains CLAUDE.md project memory files that give AI coding agents concise, non-obvious context about a codebase. It focuses on actionable conventions, recurring gotchas, and architectural decisions that agents cannot reliably infer from source alone. Use it to reduce repeated investigation and speed up agent-driven development tasks.

How this skill works

The skill inspects a repository and identifies gaps where agent conversations repeatedly surface the same questions or mistakes. It structures output into 2–4 XML-style sections (for example <ARCHITECTURE>, <CONVENTIONS>, <GOTCHAS>, <TESTING>) and writes only non-obvious, actionable guidance with references to existing docs. It also enforces the core principles: signal over noise, solve real friction, and avoid duplicating standard documentation.

When to use it

• Creating a new CLAUDE.md to capture project-specific memory before large-scale agent work
• Adding an architectural decision or design pattern that agents repeatedly need clarified
• Documenting recurring bugs, workarounds or non-obvious setup steps encountered during debugging
• Capturing conventions that linters/README don’t cover (naming quirks, private API markers)
• When agent conversations show repeated confusion about a particular code area

Best practices

• Write only non-obvious, actionable items — omit anything inferable from code or README
• Limit to 2–4 focused sections and use XML-style tags for easy parsing by agents
• Prefer file path references (e.g. src/auth/refresh.ts) over line numbers
• Link to existing documentation rather than duplicating schemas or deployment steps
• Update only for recurring, cross-cutting issues; keep one-off fixes in code comments

Example use cases

• Add a GOTCHAS entry describing a cache race: 'Acquire lock before checking cache status in src/cache/index.py'
• Document auth token behaviour: 'Tokens expire after 1 hour; background jobs must call refreshToken() in src/auth/refresh.py'
• Record a project convention: 'Use _internal suffix for private APIs not caught by linter'
• Note testing requirements: 'Integration tests require Docker; run make test before merging'
• Summarise architecture: 'Event-driven system via EventBridge; services communicate through events, not direct calls'