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.

A thorough, highly actionable body with concrete commands, a clearly sequenced workflow including validation and failure-recovery feedback loops, and well-signaled references to a design doc. Its weakness is conciseness — the 285-line body repeats several points across sections and inlines detail that progressive disclosure would move to the referenced design doc.

Suggestions

Consolidate flag/option documentation into one place (e.g. Expected inputs) and have the Canonical command path reference it rather than re-listing flags, to cut redundancy between sections.

Move the detailed Host-LLM contract and the 12 Guardrails into the referenced design doc, keeping only the most load-bearing rules inline in SKILL.md.

Trim repeated 'No LLM call' annotations across the Dependencies, Tools, and Canonical command path sections to a single stated contract.

Dimension	Reasoning	Score
Conciseness	The body is dense and largely free of basic-concept padding, but ~285 lines with notable redundancy — the 'Canonical command path' re-explains flags already covered in 'Expected inputs/outputs' and 'Dependencies', and the host-LLM contract repeats guardrail material.	3 / 5
Actionability	Copy-paste-ready commands throughout (e.g. 'oma docs verify --json', 'oma docs verify --report-file ./drift-report.md', 'oma docs lint --json --locales ko,ja') with per-mode examples covering the common cases and explicit exit-code semantics.	5 / 5
Workflow Clarity	Explicit PREPARE→ACQUIRE→REASON→ACT→VERIFY→FINALIZE scene sequence with a dedicated VERIFY checkpoint, a detailed 'Failure and recovery' section with feedback loops, and Guardrail 2's never-auto-apply confirmation gating the destructive sync patch step.	5 / 5
Progressive Disclosure	Well-sectioned overview with clear one-level-deep references (design doc for full architecture/schema/edge cases, adjacent skills), but no bundle files exist and substantial detail (canonical command path, host-LLM contract, 12 guardrails) is inlined that could live in referenced files.	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.

A strong, specific description that clearly states four concrete capabilities and provides explicit 'Use to...' trigger guidance covering when each applies. The main gap is a few missing natural synonyms (documentation, markdown, .md) and minor boundary overlap with oma-translation.

Dimension	Reasoning	Score
Specificity	Lists four concrete, distinct actions — 'Verify documentation references', 'propose updates for diff-affected docs', 'detect i18n translation drift', and 'lint translated docs for CJK style issues' — with comprehensive coverage across the skill's modes.	5 / 5
Completeness	Explicitly answers both 'what' (verify/propose/detect/lint) and 'when' via the 'Use to check if docs still match reality... to surface docs that may need updating... or to find stale or style-broken translations' trigger clauses.	5 / 5
Trigger Term Quality	Strong natural phrases ('docs still match reality', 'broken file paths, CLI commands, config keys, env vars', 'stale or style-broken translations') but omits common synonyms like 'documentation', 'markdown', and file extensions such as .md that a user might say.	4 / 5
Distinctiveness Conflict Risk	Clear niche (documentation drift detection / linting) with distinct triggers, but minor overlap risk with the adjacent oma-translation skill whose territory it borders on i18n/lint tasks.	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: first-fluke/oh-my-agent
Path: .agents/skills/oma-docs/SKILL.md
Commit: 7721120

Reviewed: 5 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.