# Enhance Docs

> Use when improving documentation structure, accuracy, and RAG readiness.

- **Type:** Skill
- **Install:** `agentstack add skill-agent-sh-agentsys-enhance-docs`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [agent-sh](https://agentstack.voostack.com/s/agent-sh)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [agent-sh](https://github.com/agent-sh)
- **Source:** https://github.com/agent-sh/agentsys/tree/main/.kiro/skills/enhance-docs
- **Website:** https://agent-sh.github.io/agentsys/

## Install

```sh
agentstack add skill-agent-sh-agentsys-enhance-docs
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# enhance-docs

Analyze documentation for readability, structure, and RAG optimization.

## Parse Arguments

```javascript
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

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

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

```markdown
To configure the plugin...
```

### RAG Chunking

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

```markdown
## Installation
[400 tokens - installation only]

## Configuration
[300 tokens - config only]

## Usage
[400 tokens - usage only]
```

### Position-Aware Content

```markdown
## Introduction
[Long background...]

## History
[More context...]

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

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

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

```markdown
| 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](https://github.com/agent-sh)
- **Source:** [agent-sh/agentsys](https://github.com/agent-sh/agentsys)
- **License:** MIT
- **Homepage:** https://agent-sh.github.io/agentsys/

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-agent-sh-agentsys-enhance-docs
- Seller: https://agentstack.voostack.com/s/agent-sh
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.