llm-docs-optimizer

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):

1. Formatting (5%): Proper structure and language tags
2. Project Metadata (5%): Absence of irrelevant content
3. 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.

1. Review the analysis report (if script was run) to understand current state:
2. Count of code snippets with issues
3. Breakdown by metric type
4. Duplicate snippets
5. 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:
2. Question-Snippet Matching (80%): How well do code examples answer developer questions?
3. LLM Evaluation (10%): Clarity, correctness, unique information
4. Formatting (5%): Proper markdown structure and language tags
5. Metadata Removal (2.5%): Absence of licenses, citations, directory trees
6. Initialization (2.5%): More than just imports/installation

1. Analyze Optimized Documentation using the same metrics

1. Calculate Scores (0-100 for each metric):
2. For Question-Snippet Matching:
3. 90-100: Excellent - Complete, practical answers with context
4. 70-89: Good - Most questions answered with working examples
5. 50-69: Fair - Partial answers, missing context
6. 30-49: Poor - Vague or incomplete answers
7. 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

1. 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]

1. Scoring Guidelines:
2. Be objective and consistent