editing-claude

What this skill does

# 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](#when-to-use) - Explicit, implicit, and file type triggers
- [What This Skill Does](#what-this-skill-does) - 8-step workflow and health scoring
- [Instructions](#instructions) - Complete implementation guide
  - [Step 1: Discover CLAUDE.md Files](#step-1-discover-claudemd-files) - Find global, project, and local files
  - [Step 2: Analyze Structure](#step-2-analyze-structure) - Parse headings, measure sections, detect orphans
  - [Step 3: Analyze Emphasis Usage](#step-3-analyze-emphasis-usage) - Count MUST/NEVER/ALWAYS markers
  - [Step 4: Detect Redundancy](#step-4-detect-redundancy) - Intra-file and cross-file duplication
  - [Step 5: Detect Contradictions](#step-5-detect-contradictions) - Find conflicting directives
  - [Step 6: Identify Extraction Opportunities](#step-6-identify-extraction-opportunities) - Content for specialized docs
  - [Step 7: Validate Links](#step-7-validate-links) - Check internal/external links
  - [Step 8: Generate Health Report](#step-8-generate-health-report) - Compile comprehensive analysis
- [Safe Automated Fixes](#safe-automated-fixes) - Fixes that can be applied automatically
  - [Fix 1: Remove Cross-File Redundancy](#fix-1-remove-cross-file-redundancy) - Replace duplication with references
  - [Fix 2: Fix Broken Links](#fix-2-fix-broken-links) - Update links to correct paths
  - [Fix 3: Fix Orphaned Sections](#fix-3-fix-orphaned-sections) - Promote or nest sections
  - [Fix 4: Reduce Emphasis Density](#fix-4-reduce-emphasis-density-2) - Remove redundant emphasis
- [Examples](#examples) - Real-world usage scenarios
- [Validation](#validation) - Verify skill execution and outcomes
- [Integration Points](#integration-points) - Quality gates, git workflow, documentation reviews

### Advanced Topics
- [Supporting Files](#supporting-files) - Scripts, templates, and references
- [Red Flags](#red-flags) - Common mistakes to avoid
- [Troubleshooting](#troubleshooting) - Common issues and fixes
- [Requirements](#requirements) - Python, bash tools, and dependencies

### Supporting Resources
- [Reference](references/reference.md) - Anthropic best practices, algorithms, validation checklist
- [Examples](examples/examples.md) - Quarterly review, redundancy fixes, extraction strategy

## Quick Start

**Analyze current CLAUDE.md:**
```bash
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:**

```bash
# 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:**

```bash
# 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:**

```bash
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:**

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

**Calculate emphasis density:**

```bash
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:

```bash
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):**

```bash
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:**

```bash
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:**

```bash
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 speci