llm-docs-optimizer

What this skill does

# LLM Docs Optimizer

This skill optimizes project documentation and README files for AI coding assistants and LLMs like Claude, GitHub Copilot, and others. It improves documentation quality through multiple approaches: c7score optimization (Context7's quality benchmark), llms.txt file generation for LLM navigation, question-driven content restructuring, and automated quality scoring across 5 key metrics.

**Version:** 1.3.0

## Understanding C7Score

C7score evaluates documentation using 5 metrics across two categories:

**LLM Analysis (85% of score):**
1. **Question-Snippet Comparison (80%)**: How well snippets answer common developer questions
2. **LLM Evaluation (5%)**: Relevancy, clarity, correctness, and uniqueness

**Text Analysis (15% of score):**
3. **Formatting (5%)**: Proper structure and language tags
4. **Project Metadata (5%)**: Absence of irrelevant content
5. **Initialization (5%)**: Not just imports/installations

For detailed information on each metric, read `references/c7score_metrics.md`.

## Core Workflow

### Step 0: Ask About llms.txt Generation (C7Score Optimization Only)

**IMPORTANT**: When the user requests c7score documentation optimization, ALWAYS ask if they also want an llms.txt file:

Use the `AskUserQuestion` tool with this question:

```
Question: "Would you also like me to generate an llms.txt file for your project?"
Header: "llms.txt"
Options:
  - "Yes, create both optimized docs and llms.txt"
    Description: "Optimize documentation for c7score AND generate an llms.txt navigation file"
  - "No, just optimize the documentation"
    Description: "Only perform c7score optimization without llms.txt generation"
```

**If user chooses "Yes"**:
- Proceed with c7score optimization workflow (Steps 1-5)
- Then follow the llms.txt generation workflow
- Provide both optimized documentation AND llms.txt file

**If user chooses "No"**:
- Proceed with c7score optimization workflow only (Steps 1-5)

**Note**: If the user explicitly requests ONLY llms.txt generation (no c7score mention), skip this step and go directly to the llms.txt generation workflow.

### Step 1: Analyze Current Documentation

When given a project or documentation to optimize:

1. **Read the documentation files** (README.md, docs/*.md, etc.)
2. **Run the analysis script** (optional but recommended) to identify issues:
   ```bash
   python scripts/analyze_docs.py <path-to-readme.md>
   ```
   Note: The script requires Python 3.7+ and is optional. You can skip it if Python is unavailable.
3. **Review the analysis report** (if script was run) to understand current state:
   - Count of code snippets with issues
   - Breakdown by metric type
   - Duplicate snippets
   - Language distribution

### Step 2: Generate Developer Questions

Create a list of 15-20 questions that developers commonly ask about the project:

- Focus on "How do I..." questions
- Cover setup, configuration, basic usage, common operations
- Include authentication, error handling, advanced features
- Think about real-world use cases

**Example questions:**
- How do I install and set up [project]?
- How do I authenticate/configure [project]?
- How do I [main feature/operation]?
- How do I handle errors?
- How do I integrate with [common tools]?

### Step 3: Map Questions to Snippets

Evaluate which questions are well-answered by existing documentation:
- ✅ Questions with complete, working code examples
- ⚠️ Questions with partial or theoretical answers
- ❌ Questions with no answers

Prioritize filling gaps for unanswered questions.

### Step 4: Optimize Documentation

Apply optimizations based on priority:

**Priority 1: Question Coverage (80% of score)**
- Add complete code examples for unanswered questions
- Transform API references into usage examples
- Ensure each major snippet answers at least one common question
- Make examples self-contained and runnable

**Priority 2: Remove Duplicates**
- Identify similar or identical snippets
- Consolidate into comprehensive examples
- Ensure each snippet provides unique value

**Priority 3: Fix Formatting**
- Use proper language tags (python, javascript, typescript, bash, etc.)
- Follow TITLE / DESCRIPTION / CODE structure
- Avoid very short (<3 lines) or very long (>100 lines) snippets
- Don't use descriptive strings as language tags

**Priority 4: Remove Metadata**
- Remove or minimize licensing snippets
- Remove directory structure listings
- Remove citations and BibTeX entries
- Keep only usage-relevant content

**Priority 5: Enhance Initialization Snippets**
- Combine import-only snippets with usage examples
- Add context to installation commands
- Always show what comes after setup

For detailed transformation patterns, read `references/optimization_patterns.md`.

### Step 5: Validate Optimizations

Before finalizing, verify each optimized snippet:

✅ Can run standalone (copy-paste works)
✅ Answers a specific developer question
✅ Provides unique information
✅ Uses proper format and language tag
✅ Focuses on practical usage
✅ Includes necessary imports/setup
✅ No licensing, citations, or directory trees
✅ Syntactically correct code

### Step 6: Evaluate C7Score Impact

After optimization, provide a c7score evaluation comparing the original and optimized documentation:

**Evaluation Process:**

1. **Analyze Original Documentation** against c7score metrics:
   - Question-Snippet Matching (80%): How well do code examples answer developer questions?
   - LLM Evaluation (10%): Clarity, correctness, unique information
   - Formatting (5%): Proper markdown structure and language tags
   - Metadata Removal (2.5%): Absence of licenses, citations, directory trees
   - Initialization (2.5%): More than just imports/installation

2. **Analyze Optimized Documentation** using the same metrics

3. **Calculate Scores** (0-100 for each metric):
   - For Question-Snippet Matching:
     - 90-100: Excellent - Complete, practical answers with context
     - 70-89: Good - Most questions answered with working examples
     - 50-69: Fair - Partial answers, missing context
     - 30-49: Poor - Vague or incomplete answers
     - 0-29: Very Poor - Questions not addressed

   - For LLM Evaluation:
     - 90-100: Unique, clear, syntactically perfect
     - 70-89: Mostly unique and clear, minor issues
     - 50-69: Some duplicates or clarity issues
     - 30-49: Significant duplicates or syntax errors
     - 0-29: Major quality problems

   - For Formatting:
     - 100: All snippets properly formatted with language tags
     - 80-99: Minor formatting issues
     - 50-79: Multiple formatting problems
     - 0-49: Significant formatting issues

   - For Metadata Removal:
     - 100: No project metadata
     - 50-99: Some metadata present
     - 0-49: Significant metadata content

   - For Initialization:
     - 100: All examples show usage beyond setup
     - 50-99: Some initialization-only snippets
     - 0-49: Many initialization-only snippets

4. **Present Results** in this format:

```markdown
## C7Score Evaluation

### Original Documentation Score: XX/100

**Metric Breakdown:**
- Question-Snippet Matching: XX/100 (weight: 80%)
  - Analysis: [Brief explanation of score]
- LLM Evaluation: XX/100 (weight: 10%)
  - Analysis: [Brief explanation]
- Formatting: XX/100 (weight: 5%)
  - Analysis: [Brief explanation]
- Metadata Removal: XX/100 (weight: 2.5%)
  - Analysis: [Brief explanation]
- Initialization: XX/100 (weight: 2.5%)
  - Analysis: [Brief explanation]

**Weighted Average:** XX/100

---

### Optimized Documentation Score: XX/100

**Metric Breakdown:**
[Same format as above]

**Weighted Average:** XX/100

---

### Improvement Summary

**Overall Improvement:** +XX points (XX → XX)

**Key Improvements:**
- [Metric]: +XX points - [What specifically improved]
- [Metric]: +XX points - [What specifically improved]

**Impact Assessment:**
[Brief explanation of how optimizations improved the documentation quality]
```

5. **Scoring Guidelines:**
   - Be objective and consistent