diff --git a/03-skills/README.md b/03-skills/README.md index c748e1d..78cbe05 100644 --- a/03-skills/README.md +++ b/03-skills/README.md @@ -1052,7 +1052,75 @@ pip install pypdf pdfplumber **Important**: Claude reads additional files only when needed, using progressive disclosure to manage context efficiently. Reference files with relative links in your SKILL.md. -### Example 5: Code Refactoring Skill +### Example 5: CLAUDE.md Generator Skill + +A skill for creating and maintaining optimal CLAUDE.md files following best practices. + +**Directory Structure:** + +``` +claude-md/ +└── SKILL.md +``` + +**File:** `~/.claude/skills/claude-md/SKILL.md` + +```yaml +--- +description: Create or update CLAUDE.md files following best practices for optimal AI agent onboarding +--- + +## Core Principles + +**LLMs are stateless**: CLAUDE.md is the only file automatically included in every conversation. It serves as the primary onboarding document for AI agents into your codebase. + +### The Golden Rules + +1. **Less is More**: Frontier LLMs can follow ~150-200 instructions. Keep your CLAUDE.md focused and concise. +2. **Universal Applicability**: Only include information relevant to EVERY session. +3. **Don't Use Claude as a Linter**: Use deterministic tools (prettier, eslint) instead. +4. **Never Auto-Generate**: Craft it manually with careful consideration. + +## Essential Sections + +A well-structured CLAUDE.md should include: + +- **Project Name**: Brief one-line description +- **Tech Stack**: Primary language, frameworks, database +- **Project Structure**: Only for monorepos or complex structures +- **Development Commands**: Install, test, build commands +- **Critical Conventions**: Only non-obvious, high-impact conventions +- **Known Issues / Gotchas**: Things that consistently trip up developers + +## Quality Constraints + +- Target under 300 lines (ideally under 100) +- No style rules (use linters) +- No code snippets (use file references) +- No task-specific instructions +``` + +**Key Features:** +- Three operation modes: `create`, `update`, `audit` +- Follows WHAT/WHY/HOW content strategy +- Progressive disclosure for larger projects via `agent_docs/` folder +- Validation checklist for quality assurance +- Anti-pattern detection and removal + +**Usage Examples:** + +``` +User: /claude-md create +Claude: [Analyzes project, creates optimized CLAUDE.md] + +User: /claude-md audit +Claude: [Reports on current CLAUDE.md quality without modifications] + +User: /claude-md update +Claude: [Improves existing CLAUDE.md following best practices] +``` + +### Example 6: Code Refactoring Skill A systematic refactoring skill based on Martin Fowler's methodology. diff --git a/03-skills/claude-md/SKILL.md b/03-skills/claude-md/SKILL.md new file mode 100644 index 0000000..eaab945 --- /dev/null +++ b/03-skills/claude-md/SKILL.md @@ -0,0 +1,211 @@ +--- +description: Create or update CLAUDE.md files following best practices for optimal AI agent onboarding +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). User may specify: +- `create` - Create new CLAUDE.md from scratch +- `update` - Improve existing CLAUDE.md +- `audit` - Analyze and report on current CLAUDE.md quality +- A specific path to create/update (e.g., `src/api/CLAUDE.md` for directory-specific instructions) + +## Core Principles + +**LLMs are stateless**: CLAUDE.md is the only file automatically included in every conversation. It serves as the primary onboarding document for AI agents into your codebase. + +### The Golden Rules + +1. **Less is More**: Frontier LLMs can follow ~150-200 instructions. Claude Code's system prompt already uses ~50. Keep your CLAUDE.md focused and concise. + +2. **Universal Applicability**: Only include information relevant to EVERY session. Task-specific instructions belong in separate files. + +3. **Don't Use Claude as a Linter**: Style guidelines bloat context and degrade instruction-following. Use deterministic tools (prettier, eslint, etc.) instead. + +4. **Never Auto-Generate**: CLAUDE.md is the highest leverage point of the AI harness. Craft it manually with careful consideration. + +## Execution Flow + +### 1. Project Analysis + +First, analyze the current project state: + +1. Check for existing CLAUDE.md files: + - Root level: `./CLAUDE.md` or `.claude/CLAUDE.md` + - Directory-specific: `**/CLAUDE.md` + - Global user config: `~/.claude/CLAUDE.md` + +2. Identify the project structure: + - Technology stack (languages, frameworks) + - Project type (monorepo, single app, library) + - Development tools (package manager, build system, test runner) + +3. Review existing documentation: + - README.md + - CONTRIBUTING.md + - package.json, pyproject.toml, Cargo.toml, etc. + +### 2. Content Strategy (WHAT, WHY, HOW) + +Structure CLAUDE.md around three dimensions: + +#### WHAT - Technology & Structure +- Technology stack overview +- Project organization (especially important for monorepos) +- Key directories and their purposes + +#### WHY - Purpose & Context +- What the project does +- Why certain architectural decisions were made +- What each major component is responsible for + +#### HOW - Workflow & Conventions +- Development workflow (bun vs node, pip vs uv, etc.) +- Testing procedures and commands +- Verification and build methods +- Critical "gotchas" or non-obvious requirements + +### 3. Progressive Disclosure Strategy + +For larger projects, recommend creating an `agent_docs/` folder: + +``` +agent_docs/ + |- building_the_project.md + |- running_tests.md + |- code_conventions.md + |- architecture_decisions.md +``` + +In CLAUDE.md, reference these files with instructions like: +```markdown +For detailed build instructions, refer to `agent_docs/building_the_project.md` +``` + +**Important**: Use `file:line` references instead of code snippets to avoid outdated context. + +### 4. Quality Constraints + +When creating or updating CLAUDE.md: + +1. **Target Length**: Under 300 lines (ideally under 100) +2. **No Style Rules**: Remove any linting/formatting instructions +3. **No Task-Specific Instructions**: Move to separate files +4. **No Code Snippets**: Use file references instead +5. **No Redundant Information**: Don't repeat what's in package.json or README + +### 5. Essential Sections + +A well-structured CLAUDE.md should include: + +```markdown +# Project Name + +Brief one-line description. + +## Tech Stack +- Primary language and version +- Key frameworks/libraries +- Database/storage (if any) + +## Project Structure +[Only for monorepos or complex structures] +- `apps/` - Application entry points +- `packages/` - Shared libraries + +## Development Commands +- Install: `command` +- Test: `command` +- Build: `command` + +## Critical Conventions +[Only non-obvious, high-impact conventions] +- Convention 1 with brief explanation +- Convention 2 with brief explanation + +## Known Issues / Gotchas +[Things that consistently trip up developers] +- Issue 1 +- Issue 2 +``` + +### 6. Anti-Patterns to Avoid + +**DO NOT include:** +- Code style guidelines (use linters) +- Documentation on how to use Claude +- Long explanations of obvious patterns +- Copy-pasted code examples +- Generic best practices ("write clean code") +- Instructions for specific tasks +- Auto-generated content +- Extensive TODO lists + +### 7. Validation Checklist + +Before finalizing, verify: + +- [ ] Under 300 lines (preferably under 100) +- [ ] Every line applies to ALL sessions +- [ ] No style/formatting rules +- [ ] No code snippets (use file references) +- [ ] Commands are verified to work +- [ ] Progressive disclosure used for complex projects +- [ ] Critical gotchas are documented +- [ ] No redundancy with README.md + +## Output Format + +### For `create` or default: + +1. Analyze the project +2. Draft a CLAUDE.md following the structure above +3. Present the draft for review +4. Write to the appropriate location after approval + +### For `update`: + +1. Read existing CLAUDE.md +2. Audit against best practices +3. Identify: + - Content to remove (style rules, code snippets, task-specific) + - Content to condense + - Missing essential information +4. Present changes for review +5. Apply changes after approval + +### For `audit`: + +1. Read existing CLAUDE.md +2. Generate a report with: + - Current line count vs target + - Percentage of universally-applicable content + - List of anti-patterns found + - Recommendations for improvement +3. Do NOT modify the file, only report + +## AGENTS.md Handling + +If the user requests AGENTS.md creation/update: + +AGENTS.md is used for defining specialized agent behaviors. Unlike CLAUDE.md (which is for project context), AGENTS.md defines: +- Custom agent roles and capabilities +- Agent-specific instructions and constraints +- Workflow definitions for multi-agent scenarios + +Apply similar principles: +- Keep focused and concise +- Use progressive disclosure +- Reference external docs instead of embedding content + +## Notes + +- Always verify commands work before including them +- When in doubt, leave it out - less is more +- The system reminder tells Claude that CLAUDE.md "may or may not be relevant" - the more noise, the more it gets ignored +- Monorepos benefit most from clear WHAT/WHY/HOW structure +- Directory-specific CLAUDE.md files should be even more focused