dawiddutoit/custom-claude/editing-claude

editing-claude

Validate and optimize CLAUDE.md files to maintain focus and effectiveness.

Purpose

This skill validates CLAUDE.md files against Anthropic's best practices, detects quality issues (contradictions, redundancy, excessive length, emphasis overuse), and suggests safe automated fixes or extraction strategies. Based on comprehensive research into context engineering best practices.

Table of Contents

Core Sections

• When to Use - Explicit, implicit, and file type triggers
• What This Skill Does - 8-step workflow and health scoring
• Instructions - Complete implementation guide
• Step 1: Discover CLAUDE.md Files - Find global, project, and local files
• Step 2: Analyze Structure - Parse headings, measure sections, detect orphans
• Step 3: Analyze Emphasis Usage - Count MUST/NEVER/ALWAYS markers
• Step 4: Detect Redundancy - Intra-file and cross-file duplication
• Step 5: Detect Contradictions - Find conflicting directives
• Step 6: Identify Extraction Opportunities - Content for specialized docs
• Step 7: Validate Links - Check internal/external links
• Step 8: Generate Health Report - Compile comprehensive analysis
• Safe Automated Fixes - Fixes that can be applied automatically
• Fix 1: Remove Cross-File Redundancy - Replace duplication with references
• Fix 2: Fix Broken Links - Update links to correct paths
• Fix 3: Fix Orphaned Sections - Promote or nest sections
• Fix 4: Reduce Emphasis Density - Remove redundant emphasis
• Examples - Real-world usage scenarios
• Validation - Verify skill execution and outcomes
• Integration Points - Quality gates, git workflow, documentation reviews

Advanced Topics

• Supporting Files - Scripts, templates, and references
• Red Flags - Common mistakes to avoid
• Troubleshooting - Common issues and fixes
• Requirements - Python, bash tools, and dependencies

Supporting Resources

• Reference - Anthropic best practices, algorithms, validation checklist
• Examples - Quarterly review, redundancy fixes, extraction strategy

Quick Start

Analyze current CLAUDE.md:

Skill(command: "editing-claude")

Expected output: Health report (0-50 score), issues found (critical/warning/info), extraction opportunities, automated fixes available.

When to Use

Explicit Triggers:

• "Edit CLAUDE.md"
• "Optimize CLAUDE.md"
• "Check for contradictions in CLAUDE.md"
• "Validate documentation"
• "CLAUDE.md is too long"

Implicit Triggers:

• Before committing CLAUDE.md changes
• Document exceeds 200 lines (warn at 200, error at 500)
• Quarterly documentation reviews
• After adding new rules/sections

File Types:

• CLAUDE.md (project or global)
• .claude/*.md (specialized docs)
• *.CLAUDE.md (local overrides)

What This Skill Does

8-Step Workflow:

1. Discovery - Find all CLAUDE.md files (global, project, local)
2. Structure Analysis - Parse headings, measure sections, detect orphans
3. Emphasis Analysis - Count MUST/NEVER/ALWAYS/MANDATORY/CRITICAL markers
4. Redundancy Detection - Find duplicate content (intra-file and cross-file)
5. Contradiction Detection - Find conflicting directives
6. Extraction Opportunities - Identify content for specialized docs
7. Link Validation - Verify all internal/external links
8. Report & Recommendations - Generate health score with prioritized fixes

Health Score Components (50 points):

• Length: 10 points (100-200 lines = 10, >500 = 0)
• Emphasis Density: 10 points (<1% = 10, >2% = 0)
• Contradictions: 10 points (0 = 10, >3 = 0)
• Redundancy: 10 points (0 instances = 10, >5 = 0)
• Links: 5 points (all valid = 5)
• Structure: 5 points (no orphans = 5)
• Extraction Potential: 5 points (<20% = 5)
• Freshness: 5 points (updated <30 days = 5)

Instructions

Step 1: Discover CLAUDE.md Files

Find all CLAUDE.md files in hierarchy:

# Global CLAUDE.md
test -f ~/.claude/CLAUDE.md && echo "Global: ~/.claude/CLAUDE.md" || echo "No global"
 
# Project CLAUDE.md
test -f ./CLAUDE.md && echo "Project: ./CLAUDE.md" || echo "No project"
 
# Get line counts
wc -l ~/.claude/CLAUDE.md ./CLAUDE.md 2>/dev/null

Read the target CLAUDE.md file (usually project).

Step 2: Analyze Structure

Extract headings and calculate section lengths:

# Extract all headings with line numbers
grep -n "^#" ./CLAUDE.md
 
# Count sections
grep -c "^## " ./CLAUDE.md  # H2 sections
grep -c "^### " ./CLAUDE.md  # H3 subsections

Use Python script for detailed analysis:

python .claude/skills/editing-claude/scripts/analyze_structure.py ./CLAUDE.md

Detect issues:

• Document >200 lines (warning), >500 lines (error)
• Sections >100 lines (suggest extraction)
• Orphaned sections (H3 without H2 parent)
• Heading hierarchy skips (H1 → H3 without H2)

Step 3: Analyze Emphasis Usage

Extract emphasis markers:

# Find all CRITICAL/MANDATORY/MUST/NEVER/ALWAYS instances
grep -n "\(CRITICAL\|MANDATORY\|MUST\|NEVER\|ALWAYS\)" ./CLAUDE.md

Calculate emphasis density:

python .claude/skills/editing-claude/scripts/analyze_emphasis.py ./CLAUDE.md

Thresholds:

• <1%: ✅ Optimal (restrained)
• 1-2%: ✅ Acceptable (within range)
• 2-5%: ⚠️ Warning (overuse)
• >5%: ❌ Error (nothing is critical)

Step 4: Detect Redundancy

Intra-file redundancy (same file):

Run semantic similarity analysis:

python .claude/skills/editing-claude/scripts/detect_redundancy.py ./CLAUDE.md

Distinguish redundancy from reinforcement:

• Redundancy: Exact duplication in same context → Fix
• Reinforcement: Same info in escalating contexts (catalog → section → checklist) → Keep

Cross-file redundancy (global vs project):

python .claude/skills/editing-claude/scripts/detect_redundancy.py ~/.claude/CLAUDE.md ./CLAUDE.md

Common redundant rules:

• MultiEdit requirement
• Testing philosophy
• Critical thinking principle

Fix: Replace project duplication with reference to global.

Step 5: Detect Contradictions

Run semantic contradiction analysis:

python .claude/skills/editing-claude/scripts/detect_contradictions.py ./CLAUDE.md

Contradiction patterns:

• Direct opposition: "ALWAYS use X" + "NEVER use X"
• Priority conflicts: "X is critical" + "X is optional"
• Conflicting delegation: Multiple agents for same task
• Tool preference conflicts: Skill vs direct tool (check if conditional)

Validation: Check if apparent contradictions are actually conditional fallbacks (not true contradictions).

Step 6: Identify Extraction Opportunities

Analyze each section:

python .claude/skills/editing-claude/scripts/identify_extractions.py ./CLAUDE.md

Extraction criteria:

• Section >50 lines
• Detailed how-to content (should be in guide)
• Low-frequency content (edge cases)
• Catalog-style content (lists of items)

Common extraction targets:

• Skills Catalog (if >40 lines) → .claude/docs/skills-index.md
• Workflow details → .claude/docs/workflow-guides.md
• Anti-pattern details → .claude/docs/enforcement-guide.md
• Agent reference → ../orchestrate-agents/references/dispatch.md (if not already there)

Keep in CLAUDE.md:

• 5 most critical items from each catalog
• Core principles (not implementation details)
• Links to specialized docs

Step 7: Validate Links

Extract and validate all links:

python .claude/skills/editing-claude/scripts/validate_links.py ./CLAUDE.md

Check:

• Internal links (file exists)
• Relative paths (not absolute)
• External links (HTTP 200) - optional
• Link text descriptive (not "click here")

Fix broken links automatically (safe operation).

Step 8: Generate Health Report

Compile all analyses into comprehensive report:

python .claude/skills/editing-claude/scripts/generate_report.py ./CLAUDE.md

Report format:

# CLAUDE.md Health Report
 
**Overall Score: X/50** 🟢 EXCELLENT | 🟡 GOOD | 🟠 NEEDS WORK | 🔴 CRITICAL
 
## Issues Found
 
### 🔴 Critical (Fix Immediately)
-[Issue with line numbers and fix]
 
### 🟠 High Priority (Fix Soon)
-[Issue with line numbers and fix]
 
### 🟡 Medium Priority (Improve)
-[Issue with line numbers and suggestion]
 
### 🟢 Low Priority (Optional)
-[Issue with line numbers and suggestion]
 
## Extraction Opportunities
-[Section] (X lines) → [target-file.md]
 
## Automated Fixes Available
-[ ] Fix 1 (safe, low-risk)
-[ ] Fix 2 (requires review)
 
## Recommendations
1.[Priority action]
2.[Next action]
3.[Future improvement]

Write report to `.claude/artifacts/YYYY-MM-DD/reports/claude-md-health-report.md`.

• Use reports/ subfolder for health reports
• If multiple reports exist for same topic, group in topic subfolder (e.g., reports/claude-md-optimization/)

Safe Automated Fixes

The following fixes can be applied automatically (with --apply flag):

Fix 1: Remove Cross-File Redundancy

When: Same rule in global and project CLAUDE.md

Action: Replace project duplication with reference to global

# Before (project CLAUDE.md)
### Token Optimization (MultiEdit Required)
[13 lines of MultiEdit explanation]
 
# After
### Token Optimization
**Global Rule:** See [~/.claude/CLAUDE.md](~/.claude/CLAUDE.md) for MultiEdit requirement

Validation: Ensure global CLAUDE.md exists and contains the rule.

Fix 2: Fix Broken Links

When: Internal link points to non-existent file

Action: Update link to correct path OR remove if file truly missing

Validation: File exists at new path AND content matches expected.

Fix 3: Fix Orphaned Sections

When: H3 section without H2 parent

Action: Promote to H2 OR nest under appropriate existing H2

Validation: Requires semantic understanding - ASK USER for confirmation.

Fix 4: Reduce Emphasis Density (>2%)

When: Too many CRITICAL/MANDATORY markers

Action: Remove redundant emphasis (e.g., heading + body both have emphasis)

Validation: Meaning preserved, emphasis still clear.

Examples

Python Examples

• analyze_structure.py - Parse headings, measure sections, detect orphans
• analyze_emphasis.py - Extract MUST/NEVER/ALWAYS, calculate density
• validate_links.py - Link extraction, existence checking
• generate_report.py - Compile analyses into comprehensive report

Complete Walkthroughs

See examples/examples.md for:

• Example 1: Quarterly Review - Full analysis workflow
• Example 2: Fixing Redundancy - Cross-file duplication
• Example 3: Extraction Strategy - Skills Catalog extraction
• Example 4: Contradiction Resolution - Detecting conflicts
• Example 5: Length Optimization - 502 → 250 lines
• Example 6: Emergency Fix - Broken links and orphans

Supporting Files