claude-md-writer_skill

Overview

This skill helps create and refactor CLAUDE.md files to follow Anthropic best practices for size, structure, and conditional loading. It enforces concise main files, modular rules, path-specific loading, and a clear memory hierarchy so Claude loads only what’s necessary. Use it to reduce token costs and improve maintainability across projects.

How this skill works

The skill inspects CLAUDE.md and .claude/rules/ content, checks line counts, identifies task-specific material to extract, and validates YAML frontmatter with paths globs. It suggests breaking large files into modular rules, ordering critical rules first, and replacing duplicated content with file pointers. It also verifies memory hierarchy placement and recommends CLAUDE.local.md for personal preferences.

When to use it

• Creating a new CLAUDE.md for a project
• Refactoring an oversized CLAUDE.md (>200–300 lines)
• Organizing domain-specific guidance into .claude/rules/
• Adding path-specific rules to reduce token load
• Auditing project memory hierarchy and file loading order

Best practices

• Keep main CLAUDE.md under ~200 lines; prefer <100 for new projects
• Put critical constraints at the top so they load first
• Move SQL, deployment, and API docs to .claude/rules/ with <500 lines each
• Use YAML frontmatter paths: load rules only when matching files
• Reference files with @pointers instead of copying content
• Store personal prefs in CLAUDE.local.md (gitignored)

Example use cases

• Run /init to bootstrap a minimal CLAUDE.md and then trim to essentials
• Refactor a 700-line CLAUDE.md: extract database.md, deploy.md, api.md into .claude/rules/
• Add paths: 'src/api/**/*.ts' to API rules so they load only during backend work
• Create component-specific rules under .claude/rules/frontend/ with globs for UI files
• Replace repeated deployment steps with @deploy.md pointers to keep docs single-sourced