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:

   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:

## 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