oma-docs

Verify documentation references against the current codebase, propose updates for diff-affected docs, detect i18n translation drift, and lint translated docs for CJK style issues. Use to check if docs still match reality (broken file paths, CLI commands, config keys, env vars, scripts), to surface docs that may need updating after code changes, or to find stale or style-broken translations.

Quality

86%

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

81%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 delivers highly actionable, well-sequenced guidance with strong validation and feedback loops for a destructive-capable skill, and references are clearly signaled one level deep. Its main drag is conciseness — repeated dependency listings and an ornamental SSL-primitive table pad the context without adding actionable value.

Suggestions

Consolidate the CLI dependency list so each file (extract.ts, resolve.ts, reporter.ts, etc.) is described once; remove the duplicate descriptions in 'Tools and instruments' or 'Dependencies' rather than restating them.

Drop or justify the 'SSL primitive' column in the Actions table — the READ/CALL_TOOL/RESOLVE labels add ceremony that does not guide Claude's execution.

Move the full Guardrails list (or the per-mode Transitions detail) into a referenced file (e.g. GUARDRAILS.md) and keep SKILL.md as a leaner overview, improving both conciseness and progressive disclosure.

Dimension	Reasoning	Score
Conciseness	The body is information-dense and avoids teaching concepts Claude already knows, but it duplicates the CLI dependency list across 'Dependencies', 'Tools and instruments', and the Actions table, and the ornamental 'SSL primitive' column adds ceremony without actionable value; tightening the duplications would move it toward a 4, while the padding is more than 'minor' so it does not yet qualify.	3 / 5
Actionability	The 'Canonical command path' provides copy-paste-ready, executable bash for all four modes with flags, exit codes, and output locations, and the host-LLM contract gives concrete per-mode steps — fully executable coverage of the common cases.	5 / 5
Workflow Clarity	Sequencing is explicit (PREPARE→ACQUIRE→REASON→ACT→VERIFY→FINALIZE per mode) with validation checkpoints (JSON schema check, 'VALIDATE'/'VERIFY' steps), feedback loops in 'Failure and recovery', and per-doc interactive confirmation for the destructive sync patch step — satisfying the anchor's checklists and error-recovery loops.	5 / 5
Progressive Disclosure	Structure is clean with well-labeled sections and a one-level-deep References pointer to the design doc, but no bundle files exist and a fair amount of architecture detail (full guardrails list, SSL actions table) is inlined in SKILL.md rather than split into referenced files, leaving minor organization gaps short of the 'appropriately split' anchor 5.	4 / 5
	Total	17 / 20 Passed

Description

92%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 concrete, trigger-rich, and cleanly distinguishes the skill's niche, explicitly covering both what it does and when to use it across four modes. Its only weakness is the absence of explicit file-extension terms, which keeps trigger term quality just short of the top anchor.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions across four modes — 'Verify documentation references', 'propose updates for diff-affected docs', 'detect i18n translation drift', 'lint translated docs for CJK style issues' — plus concrete reference types (file paths, CLI commands, config keys, env vars, scripts), giving comprehensive coverage rather than the minor gaps of a 4.	5 / 5
Completeness	Explicitly answers both what (the four verify/sync/i18n/lint actions) and when ('Use to check if docs still match reality ... or to find stale or style-broken translations') with concrete trigger phrases, matching the anchor 5 example structure.	5 / 5
Trigger Term Quality	Strong natural-phrase coverage — 'docs still match reality', 'broken file paths', 'docs that may need updating after code changes', 'stale or style-broken translations' — with good synonyms, but it omits explicit file extensions (e.g. .md) that anchor 5 calls for, so it sits noticeably above the midpoint rather than at the top.	4 / 5
Distinctiveness Conflict Risk	Occupies a clear niche — documentation drift detection plus CJK/i18n linting — with specific trigger types unlikely to fire for unrelated skills, matching the 'clear niche with distinct triggers; minimal conflict risk' anchor.	5 / 5
	Total	19 / 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: first-fluke/oh-my-agent
Path: .agents/skills/oma-docs/SKILL.md
Commit: 032c988

Reviewed: 2 days 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.