CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

phoenix-docs-gap-audit

Audit documentation gaps across the Phoenix repo by analyzing recent commits to main (default: last 7 days). Use this skill whenever the user asks to find undocumented features, identify docs gaps, audit what shipped without docs, check which recent changes need documentation, review stale docs against current code, or mentions "documentation debt", "doc coverage", "undocumented APIs", or "what's missing from /docs". Also trigger on requests like "what from last week needs docs", "find stale READMEs", or "check docstring coverage for recent changes". Covers /docs (Mintlify), package READMEs, package-level built-in docs (Sphinx, TypeDoc), Python docstrings, TSDoc, and code comments.

Quality

91%

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

85%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 unusually actionable, well-sequenced audit workflow with concrete commands, path tables, and verification checkpoints throughout. The main weaknesses are a single monolithic file where several large blocks (report template, decision table, surface checklists) should be offloaded to reference files, and a few paragraphs of motivational padding.

Suggestions

Move the full report format template, the decision quick reference table, and the per-surface Phase 4 checklists into references/ files (e.g. references/report-template.md, references/decision-table.md) and link them from SKILL.md, keeping only a summary inline — this would cut the main file substantially and let a session load only what it needs.

Trim motivational prose to single-line imperatives: replace the "This skill is deliberately thorough. Documentation gaps are expensive..." paragraph and the "It is tempting to find a huge breaking change..." paragraph with one-line rules ("Be thorough: gaps are expensive"; "Enumerate all candidates before going deep").

The grounding-rules prose repeats ideas already enforced by the pre-submit checklist (verified paths, no invented APIs); consolidate them into one section to remove redundancy.

DimensionReasoningScore

Conciseness

The body is dominated by high-value, non-obvious domain guidance (path tables, exact git commands, triage rules), but includes a few motivational asides Claude does not need — "This skill is deliberately thorough. Documentation gaps are expensive: users hit undocumented features blind..." and "It is tempting to find a huge breaking change and spend the rest of the audit documenting it" — which could be trimmed to one line each. This is minor over-explanation, matching the efficient-with-trimmable-instances anchor rather than the lean every-token-earns-its-place anchor.

4 / 5

Actionability

Guidance is fully executable: copy-paste git commands (fetch origin main, log with --name-status, rev-list count), a concrete grep-then-read-±30-lines search strategy, per-language surface checklists with real paths, a complete report template, and a decision quick-reference table with specific answers. It covers the common cases (Python, TS, server, UI changes) with specific commands and file paths.

5 / 5

Workflow Clarity

Five clearly sequenced phases (gather commits → triage → locate code → check surfaces → classify) with explicit checkpoints: the triage buckets with defaults ("Default to reading the diff"), the breadth-before-depth rule, grounding rules that act as inline verification, and a pre-submit checklist that functions as a final validation gate. This is a read-only audit, so the destructive-operation validation cap does not apply.

5 / 5

Progressive Disclosure

The body is well-sectioned with clear headers, but there are no bundle files at all — the ~360-line SKILL.md inlines everything, including the full report format template, the decision quick reference, and the per-surface checklists, all of which clearly belong in separate reference files a follow-up session could load selectively. Structure is good but content that should be separate is inline, matching the middle anchor rather than the mostly-appropriately-placed one.

3 / 5

Total

17

/

20

Passed

Description

96%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: third-person, concrete about what the skill does, and unusually thorough on natural trigger phrases with both explicit phrasing-based and task-based triggers. The only weaknesses are mild verbosity and a few trigger phrases generic enough to overlap with general documentation skills.

DimensionReasoningScore

Specificity

The description lists multiple concrete actions — "analyzing recent commits to main (default: last 7 days)", "find undocumented features", "review stale docs against current code", "check docstring coverage" — and enumerates the doc surfaces covered (Mintlify, READMEs, Sphinx, TypeDoc, docstrings, TSDoc, comments), giving comprehensive rather than minor-gap coverage.

5 / 5

Completeness

Both halves are explicit: the "what" (audit documentation gaps across the Phoenix repo by analyzing recent commits, with the doc surfaces enumerated) and a full "Use this skill whenever..." clause with concrete trigger phrases, matching the anchor that clearly and explicitly answers both what and when.

5 / 5

Trigger Term Quality

It covers natural phrasings users would actually say across many synonyms: "documentation debt", "doc coverage", "undocumented APIs", "what's missing from /docs", "find stale READMEs", "what from last week needs docs", and "check docstring coverage for recent changes" — matching the comprehensive-with-synonyms top anchor.

5 / 5

Distinctiveness Conflict Risk

The description is anchored to a clear niche — auditing the Phoenix repo specifically for gaps, explicitly producing a gap report rather than writing docs — so it is mostly distinct. However, generic triggers like "find stale READMEs" or "identify docs gaps" could overlap a general documentation-editing skill, which is minor overlap risk rather than minimal.

4 / 5

Total

19

/

20

Passed

Validation

87%

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

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

metadata_field

'metadata' should map string keys to string values

Warning

Total

14

/

16

Passed

Repository

Arize-ai/phoenix

Path

.agents/skills/phoenix-docs-gap-audit/SKILL.md

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.