agentsys 5.1.0 → 5.2.0

package/adapters/opencode/skills/enhance-docs/SKILL.md

@@ -1,287 +0,0 @@
----
-name: enhance-docs
-description: "Use when improving documentation structure, accuracy, and RAG readiness."
-version: 5.1.0
-argument-hint: "[path] [--fix] [--ai]"
----
-
-> **OpenCode Note**: Invoke agents using `@agent-name` syntax.
-> Available agents: task-discoverer, exploration-agent, planning-agent,
-> implementation-agent, deslop-agent, delivery-validator, sync-docs-agent, consult-agent
-> Example: `@exploration-agent analyze the codebase`
-
-
-# enhance-docs
-
-Analyze documentation for readability, structure, and RAG optimization.
-
-## Parse Arguments
-
-*(JavaScript reference - not executable in OpenCode)*
-
-## 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 |
-| <50 tokens | Too short, merge with related content |
-| 200-500 tokens | Optimal for retrieval |
-
-**Semantic boundaries:**
-- Single topic per section
-- Self-contained sections (avoid "It", "This" at section start)
-- Clear section titles that describe content
-
-**Context anchors:**
-```markdown
-# Bad - ambiguous start
-## Configuration
-It requires several settings...
-
-# Good - self-contained
-## Configuration
-The plugin configuration requires several settings...
-```
-
-### 5. Information Density (MEDIUM - AI Mode)
-
-**Prefer tables over prose:**
-*(JavaScript reference - not executable in OpenCode)*
-
-**Prefer lists over paragraphs** for sequential items.
-
-**Use code blocks** for examples, commands, configurations.
-
-### 6. Cross-Reference Quality (MEDIUM)
-
-- Internal links should use relative paths
-- External links should be stable (avoid commit hashes)
-- Reference sections should point to canonical sources
-
-### 7. Balance Suggestions (MEDIUM - Both Mode)
-
-- Missing section headers in long content (>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** | - | - |
-
-<examples>
-### Verbose Phrase
-<bad_example>
-```markdown
-In order to configure the plugin, you need to...
-```
-</bad_example>
-<good_example>
-```markdown
-To configure the plugin...
-```
-</good_example>
-
-### RAG Chunking
-<bad_example>
-```markdown
-## Installation
-[2000+ tokens of mixed content covering install, config, and usage]
-```
-</bad_example>
-<good_example>
-```markdown
-## Installation
-[400 tokens - installation only]
-
-## Configuration
-[300 tokens - config only]
-
-## Usage
-[400 tokens - usage only]
-```
-</good_example>
-
-### Position-Aware Content
-<bad_example>
-```markdown
-## Introduction
-[Long background...]
-
-## History
-[More context...]
-
-## Critical Setup Steps
-[Important info buried in middle]
-```
-</bad_example>
-<good_example>
-```markdown
-## Quick Start (Critical)
-[Important setup steps at START]
-
-## Background
-[Supporting context in middle]
-
-## Reference
-[Details...]
-
-## Key Reminders
-[Critical points repeated at END]
-```
-</good_example>
-
-### Tables vs Prose
-<bad_example>
-```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`.
-```
-</bad_example>
-<good_example>
-```markdown
-| Param | Required | Default |
-|-------|----------|---------|
-| query | Yes | - |
-| limit | No | 10 |
-| format | No | json |
-```
-</good_example>
-</examples>
-
-## 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