/optimize-cc-md

name: optimize-cc-md
description: Interactively helps users optimize their CLAUDE.md files. Use when user asks to "optimize my CLAUDE.md", "my CLAUDE.md is too long", "improve organization", or "split my CLAUDE.md". Runs validation, explains issues conversationally, and helps create @import files to reduce size and improve structure.
version: 1.0.0
argument-hint: "[path]"
allowed-tools:
  - Bash(claudelint:*)
  - Read
  - Edit
  - Write
  - Grep

Optimize CLAUDE.md

An interactive skill that helps you optimize your CLAUDE.md file through a 3-phase workflow: validate, assess quality, then make guided improvements. Each phase builds on the previous one so the user understands what's wrong, why it matters, and what to do about it.

Usage

Invoke with `/optimize-cc-md` or say "optimize my CLAUDE.md". Optionally pass a path: `/optimize-cc-md CLAUDE.md`. The skill guides you through three phases: validation, quality assessment, and guided improvement.

If a specific path is provided, optimize that file: $ARGUMENTS

Workflow Overview

Phase A: Validate         Phase B: Assess Quality     Phase C: Guided Improvement
─────────────────         ───────────────────────     ───────────────────────────
Run claudelint         →  Explain issues plainly   →  Ask user what to fix
Read CLAUDE.md         →  Check quality criteria   →  Make surgical changes
Collect violations     →  Identify opportunities   →  Create @import files
                                                   →  Verify results

Phase A: Validate

Run automated validation and read the file to understand its current state.

Step 1: Run Validation

Use the Bash tool to run claudelint validation with verbose output:

npx claude-code-lint validate-claude-md --verbose

This identifies all CLAUDE.md issues including:

• File size violations (30KB warning, 50KB error)
• Missing or circular @imports
• Organization problems
• Invalid frontmatter in .claude/rules/ files
• Glob pattern issues

Step 2: Read the CLAUDE.md File

Use the Read tool to examine the user's CLAUDE.md:

Read(file_path: "CLAUDE.md")

Understand the current structure, content, and patterns. Note:

• Total file size and number of sections
• Which sections are project-specific vs generic
• Existing @import structure (if any)
• Content that could be scoped with globs

Phase B: Assess Quality

Go beyond automated checks. Explain issues conversationally and evaluate quality using criteria that linting can't catch.

Step 3: Explain Issues Conversationally

Translate validation errors into plain language:

• "Your CLAUDE.md is 45KB - that's over the 30KB warning threshold"
• "You have generic advice that could be removed"
• "These sections could be split into @import files"

Focus on the "why" not just the "what". Help users understand the impact.

Step 4: Assess Against Quality Criteria

Walk through the key quality dimensions from [quality criteria](./references/quality-criteria.md):

• **Specificity**: Is every instruction project-specific? Flag generic advice ("always write clean code")
• **Completeness**: Can a new developer build, test, and contribute?
• **Clarity**: Are instructions directive ("do X") vs descriptive ("X is important")?
• **Organization**: Is the most important info near the top? Are related items grouped?
• **Maintenance**: Do commands and paths still work? Any stale content?

Present a brief assessment to the user:

"Your CLAUDE.md has 3 validation errors and some quality gaps:
- 45KB (over 30KB threshold) - needs splitting
- 12 generic statements that should be removed
- Testing section is thorough but git workflow is missing
- Good: all commands are current and paths are valid"

Step 5: Identify Improvement Opportunities

For each issue, determine the root cause and link to reference files:

• **Size violations**: See [size optimization](./references/size-optimization.md)
• **Import issues**: See [import patterns](./references/import-patterns.md)
• **Organization**: See [organization guide](./references/organization-guide.md)
• **Templates**: See [templates](./references/templates.md) for good CLAUDE.md examples

Phase C: Guided Improvement

Let the user choose what to fix, then make the changes and verify results.

Step 6: Ask User What to Fix

Use the AskUserQuestion tool to present prioritized options:

What would you like me to fix first?

1. Reduce file size (45KB → under 30KB)
2. Fix circular import in git-workflow.md
3. Split content into organized @imports
4. Remove generic/obvious content

Let the user prioritize. Don't assume.

Step 7: Make the Changes

Use the Edit tool for surgical changes to CLAUDE.md:

Edit(
  file_path: "CLAUDE.md",
  old_string: "existing content to replace",
  new_string: "new content"
)

For removing content:

• Delete generic advice ("always write clean code")
• Remove config duplication (if same rules in .claude/settings.json)
• Clean up obvious statements that add no value

Step 8: Create @Import Files (If Splitting Content)

Use the Write tool to create new files in .claude/rules/:

Write(
  file_path: ".claude/rules/git-workflow.md",
  content: "---\nglob: \"**/*.{ts,js}\"\n---\n\n# Git Workflow\n\n..."
)

Then update CLAUDE.md to import the file:

Edit(
  file_path: "CLAUDE.md",
  old_string: "# Git Workflow\n\nLong content here...",
  new_string: "@import .claude/rules/git-workflow.md"
)

**Best practices for @imports:**

• Use .claude/rules/ for project-specific rules
• Add frontmatter with glob patterns to scope rules
• Keep import depth under 3 levels
• Avoid circular imports

Step 9: Verify Results

Run validation again to confirm fixes:

npx claude-code-lint validate-claude-md --verbose

Show before/after comparison:

• "Before: 45KB with 12 violations"
• "After: 28KB with 0 violations"
• "Changes made: Split 3 sections into @imports, removed 2