Enhance Docs

enhance-docs

Analyze documentation for readability, structure, and RAG optimization.

Parse Arguments

const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const targetPath = args.find(a => !a.startsWith('--')) || '.';
const fix = args.includes('--fix');
const aiMode = args.includes('--ai');

Documentation Locations

| Type | Location | Purpose | |------|----------|---------| | User docs | docs/*.md, README.md | Human-readable guides | | Agent docs | agent-docs/*.md | AI reference material | | Project memory | CLAUDE.md, AGENTS.md | AI context/instructions |

Optimization Modes

AI-Only Mode (--ai)

For agent-docs and RAG-optimized documentation:

• Aggressive token reduction
• Dense information packing
• Self-contained sections for retrieval
• Optimal chunking boundaries

Both Mode (--both, default)

For user-facing documentation:

• Balance readability with AI-friendliness
• Clear structure for both humans and retrievers

Workflow

1. Discover - Find all .md files
2. Parse - Extract structure and content
3. Check - Run pattern checks based on mode
4. Report - Generate markdown output
5. Fix - Apply auto-fixes if --fix

Detection Patterns

1. Link Validation (HIGH)

• Broken anchor links ([text](#missing-anchor))
• Links to non-existent files
• Malformed link syntax

2. Structure Validation (HIGH)

Heading hierarchy:

• No jumps (H1 → H3 without H2)
• Single H1 per document
• Code blocks with language tags

Position-aware content (based on "lost in the middle" research):

• Critical info at START or END of document
• Supporting details in MIDDLE
• Flag important content buried in middle sections

Recommended structure:

1. Overview/Purpose (START - high attention)
2. Quick Start / TL;DR
3. Detailed Content
4. Reference / API
5. Summary / Key Points (END - high attention)

3. Token Efficiency (HIGH - AI Mode)

Token estimation: characters / 4 or words * 1.3

Unnecessary prose:

• "In this document..."
• "As you can see..."
• "Let's explore..."
• "It's important to note that..."

Verbose phrases: | Verbose | Concise | |---------|---------| | "in order to" | "to" | | "due to the fact that" | "because" | | "has the ability to" | "can" | | "at this point in time" | "now" | | "for the purpose of" | "for" | | "in the event that" | "if" |

Target: ~1500 tokens for project memory files, flexible for reference docs.

4. RAG Optimization (MEDIUM - AI Mode)

Chunk size guidelines: | Size | Issue | |------|-------| | >1000 tokens | Too long, split into subtopics | | 500 words without heading)

• Important information buried late in document
• Missing TL;DR or summary for long documents

Auto-Fixes

| Issue | Fix | |-------|-----| | Inconsistent headings | H1 → H3 becomes H1 → H2 | | Verbose phrases | Replace with concise alternatives | | Missing code language | Add based on content detection |

Output Format

## Documentation Analysis: {name}

**File**: {path}
**Mode**: {AI-only | Both}
**Tokens**: ~{count}

| Certainty | Count |
|-----------|-------|
| HIGH | {n} |
| MEDIUM | {n} |

### Link Issues
| Line | Issue | Fix | Certainty |

### Structure Issues
| Line | Issue | Fix | Certainty |

### Efficiency Issues [AI mode]
| Line | Issue | Fix | Certainty |

### RAG Issues [AI mode]
| Line | Issue | Fix | Certainty |

Pattern Statistics

| Category | Patterns | Mode | Certainty | |----------|----------|------|-----------| | Links | 3 | shared | HIGH | | Structure | 4 | shared | HIGH | | Token Efficiency | 3 | ai | HIGH | | RAG Optimization | 3 | ai | MEDIUM | | Information Density | 2 | ai | MEDIUM | | Cross-Reference | 2 | shared | MEDIUM | | Balance | 3 | both | MEDIUM | | Total | 20 | - | - |

Verbose Phrase

In order to configure the plugin, you need to...

To configure the plugin...

RAG Chunking

## Installation
[2000+ tokens of mixed content covering install, config, and usage]

## Installation
[400 tokens - installation only]

## Configuration
[300 tokens - config only]

## Usage
[400 tokens - usage only]

Position-Aware Content

## Introduction
[Long background...]

## History
[More context...]

## Critical Setup Steps
[Important info buried in middle]

## Quick Start (Critical)
[Important setup steps at START]

## Background
[Supporting context in middle]

## Reference
[Details...]

## Key Reminders
[Critical points repeated at END]

Tables vs Prose

The API accepts three parameters. The first is `query` which is required.
The second is `limit` which defaults to 10. The third is `format`.

| Param | Required | Default |
|-------|----------|---------|
| query | Yes | - |
| limit | No | 10 |
| format | No | json |

References

• agent-docs/CONTEXT-OPTIMIZATION-REFERENCE.md - Token budgeting, position awareness, chunking
• agent-docs/PROMPT-ENGINEERING-REFERENCE.md - Structure, information density

Constraints

• Auto-fix only HIGH certainty issues
• Preserve original tone and style
• Balance AI optimization with human readability (default mode)
• Don't remove content, only restructure or condense

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: agent-sh
• Source: agent-sh/agentsys
• License: MIT
• Homepage: https://agent-sh.github.io/agentsys/

Install and usage instructions live in the source repository linked above.