CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

75

Quality

94%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

93%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.

An exemplary instruction-only skill body: tight, doctrine-dense, immediately actionable, and cleanly split across two real reference files. The only meaningful gap is validation asymmetry — generate mode has a self-audit and checklist, but the destructive compress mode and the module-map mode lack their own verification steps or retry loops.

DimensionReasoningScore

Conciseness

The body is lean and table-driven with zero padding: it never explains what documentation or CLAUDE.md is, assumes Claude's competence ("`ls` shows this", "The signature says this"), and every section carries skill-specific doctrine (line budgets, research statistics, anti-pattern examples). This matches 'lean and efficient; every token earns its place' — nothing here explains a concept Claude already knows.

5 / 5

Actionability

For an instruction-only skill the guidance is fully concrete: exact line targets (<80/<100/<150), a fill-in-the-blank audit report template, literal commands (`ls backend/src/modules/`), binary keep/delete decision rules, and named template files to apply. This matches 'fully executable... specific examples cover the common cases'; the scoring note confirms instruction-only skills are judged on concrete guidance, which this delivers.

5 / 5

Workflow Clarity

All four modes are clearly numbered and sequenced, with explicit checkpoints in the generate path (step 5 'Self-audit before delivering') and a final Quality Checklist. It falls short of score 5 because there is no fix-and-retry feedback loop and the compress mode — which destructively deletes document lines — has no post-compression validation that critical content survived, and the module-map mode has no verification step. Score 4 ('clear sequence with most checkpoints present; minor validation gaps'), not 3, because validation does exist (checklist + self-audit), so the destructive-operation cap does not apply.

4 / 5

Progressive Disclosure

The ~130-line overview holds only principles and process, deferring research detail to 'references/research-foundations.md' and templates to 'references/templates.md' — both real, substantive files, referenced exactly where needed and only one level deep. This matches 'clear overview with well-signaled one-level-deep references; content appropriately split'.

5 / 5

Total

19

/

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.

A strong description: concrete third-person capability statement, explicit and extensive trigger guidance, and a clearly framed research-backed niche. The only weaknesses are a capability sentence that omits the module-map mode and a few generic trigger phrases that slightly overlap with general documentation work.

DimensionReasoningScore

Specificity

"Generate, audit, and compress AI-optimized documentation for codebases" names three concrete actions with a clear domain, but the fourth capability (module-level documentation map generation) is absent from the capability sentence. This matches 'lists several specific actions; minor gaps in coverage' — above score 3 (more than 1-2 actions, near-comprehensive) but below score 5, which requires full coverage of the skill's modes.

4 / 5

Completeness

It explicitly answers what ("Generate, audit, and compress AI-optimized documentation for codebases... applies research-backed principles from three peer-reviewed papers") and when ("Use this skill whenever the user asks to... or mentions documentation bloat, token waste, or AI context efficiency") with concrete trigger phrases. This is a direct match for the score-5 anchor; the 'Use when' clause is explicit, so no cap applies.

5 / 5

Trigger Term Quality

The description covers natural phrases users would actually say ("write docs", "create a CLAUDE.md", "compress docs", "audit documentation", "review doc quality") plus secondary triggers like "documentation bloat", "token waste", and named research findings. This matches the 'comprehensive coverage of natural terms including synonyms' anchor; nothing common is missing.

5 / 5

Distinctiveness Conflict Risk

The AI-optimization framing and distinctive triggers ("Lost in the Middle", "AGENTS.md", "AI context efficiency") establish a clear niche, but generic phrases like "write docs", "document a module", and "create domain documentation" carry minor overlap risk with general documentation/writing skills. Mostly distinct with minor overlap — score 4, not 5, because the broad doc-writing triggers are not uniquely owned by this skill.

4 / 5

Total

18

/

20

Passed

Validation

100%

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
Reviewed

Table of Contents

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.