ai-docs

Generate, audit, and compress AI-optimized documentation for codebases. This skill applies research-backed principles from three peer-reviewed papers to create documentation that maximizes AI agent performance instead of degrading it. Use this skill whenever the user asks to "write docs", "create a CLAUDE.md", "document a module", "audit documentation", "compress docs", "optimize docs for AI", "write module docs", "create domain documentation", "review doc quality", or mentions documentation bloat, token waste, or AI context efficiency. Also trigger when the user references "ai-docs principles", "telegram style docs", or wants to apply the "Lost in the Middle", "Less is More", or "AGENTS.md" research findings.

Quality

85%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

78%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is well-structured and actionable, splitting research detail and templates into clearly signaled reference files while keeping the overview concise. The main improvement opportunity is tightening the few verbose preambles and adding an explicit error-recovery loop to the audit/compress workflows.

Suggestions

Trim preamble phrases like 'Before writing or auditing any documentation, internalize these research-backed principles:' to keep the body leaner.

Add an explicit validate→fix→retry loop to the audit and compress modes (e.g., 'If the audit finds removable lines, delete them and re-run the redundancy check until clean').

Replace some placeholder-only fields in the audit report template with one short concrete example so the output format is unambiguous.

Dimension	Reasoning	Score
Conciseness	Mostly lean — it uses compact tables and bullets, assumes Claude knows FastAPI and standard tooling, and avoids explaining basics — but the intro line and a few preamble phrases ('internalize these research-backed principles') could be trimmed.	4 / 5
Actionability	Provides concrete targets (80/100/150 lines), a copy-paste audit-report template, specific commands ('ls backend/src/modules/'), and a compression report format, with only minor gaps since the audit template still uses placeholder fields.	4 / 5
Workflow Clarity	Each of the four modes is a clearly numbered sequence with validation checkpoints ('Self-audit before delivering' and a final Quality Checklist), but it lacks an explicit validate→fix→retry error-recovery loop.	4 / 5
Progressive Disclosure	Clear overview in the body with well-signaled one-level-deep references ('read references/research-foundations.md', 'Read references/templates.md'), both of which exist as real files, with content appropriately split across them.	5 / 5
	Total	17 / 20 Passed

Description

91%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is strong: it states concrete capabilities, provides an exhaustive set of natural trigger phrases, and clearly separates 'what' from 'when'. Its only weakness is that several trigger phrases are generic enough to overlap with ordinary documentation skills.

Dimension	Reasoning	Score
Specificity	Lists three concrete actions — 'Generate, audit, and compress AI-optimized documentation' — with comprehensive coverage of the skill's modes, but the broad 'documentation' domain leaves minor gaps versus the most exhaustive anchor.	4 / 5
Completeness	Explicitly states both what it does ('Generate, audit, and compress...') and when to use it ('Use this skill whenever the user asks to...' plus 'Also trigger when...') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Comprehensive natural-term coverage including synonyms and specific markers — 'write docs', 'create a CLAUDE.md', 'compress docs', 'token waste', 'AGENTS.md', 'Lost in the Middle' — matching the anchor's expectation of synonyms and extensions.	5 / 5
Distinctiveness Conflict Risk	Has a clear AI-docs niche with distinct paper-backed triggers, but generic phrases like 'write docs' and 'document a module' create minor overlap risk with plain documentation skills.	4 / 5
	Total	18 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: alpacapurpura/luana-method
Path: claude/skills/ai-docs/SKILL.md
Commit: caa08df

Reviewed: ~22 hours ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.