CtrlK
BlogDocsLog inGet started
Tessl Logo

oma-docs

Check documentation references, sync docs to code changes, and detect translation drift. Use for documentation maintenance in a repository.

67

Quality

81%

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

88%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 an exceptionally lean operational spec: clear mode routing, copy-ready CLI commands, an explicit validation loop, and a failure/recovery table that covers the realistic failure modes. Its only real gap is that the referenced `resources/commands.md` (and the sibling/shared files) are absent from the bundle, so the deferred detail a user needs for flags and outputs is unreachable.

Suggestions

Include `resources/commands.md` in the bundle (or inline the minimal flag set for each mode) so the deferred per-mode details are actually reachable.

Since two references point outside the skill (`../oma-translation/SKILL.md`, `../_shared/core/execution-policy.md`), briefly state expected behavior when those files are unavailable, mirroring the 'Missing CLI' fallback row.

DimensionReasoningScore

Conciseness

Every section carries operational content — mode routing, command names, failure recoveries, guardrails — with zero explanation of concepts Claude already knows. The dense 'Missing CLI' row is long but every clause is an actionable instruction, matching 'every token earns its place'.

5 / 5

Actionability

Concrete executable commands are given for all four modes (`oma docs verify --json`, `oma docs sync <range> --json`, etc.) plus a fully specified manual fallback (extract `[text](path)`/`href` targets, resolve relative to containing file). Not 5 because exact flags and output-file details are deferred to `resources/commands.md`, which is not present in the bundle — the body alone is not copy-paste complete for the common cases.

4 / 5

Workflow Clarity

The canonical command path is a clear 5-step sequence with explicit validation checkpoints ('Re-run affected checks after edits and record remaining failures') and a full failure/recovery table providing feedback loops for each failure mode (patch fails → re-read and apply equivalent correction; index write fails → report, don't claim completion).

5 / 5

Progressive Disclosure

Good structure with well-signaled, one-level-deep references: mode details deferred to `resources/commands.md` ('Read only the matching section'), authorization policy and translation routed to external files, and a bottom References section. Not 5 because the primary reference target `resources/commands.md` does not exist in the bundle — navigation dead-ends — and two of three references point outside the skill.

4 / 5

Total

18

/

20

Passed

Description

75%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 a solid third-person statement with an explicit 'Use when' clause and three concrete capabilities. Its main weaknesses are a generic trigger surface and 'when' guidance that lacks the concrete phrases and synonyms (broken links, readme, markdown) that would let users reach it naturally.

Suggestions

Broaden trigger terms with natural synonyms users actually say, e.g. 'Use when the user mentions docs, README, broken links, out-of-date documentation, or translation drift.'

Make the 'when' clause more concrete with trigger phrases rather than the abstract 'documentation maintenance in a repository'.

Consider naming the fourth capability (linting localized prose / URL verification) so the description covers all four modes the body supports.

DimensionReasoningScore

Specificity

Three concrete actions are named — "Check documentation references", "sync docs to code changes", "detect translation drift" — which matches the anchor for several specific actions with minor coverage gaps (lint/style checking from the body is omitted). Not 5 because coverage is not comprehensive: no mention of localized-prose linting, URL verification, or report generation that the body supports.

4 / 5

Completeness

Both parts are explicit: what ("Check documentation references, sync docs to code changes, and detect translation drift") and when ("Use for documentation maintenance in a repository"). The 'when' clause is present but general — no concrete trigger phrases like 'when the user mentions docs, links, or translations' — so it matches the anchor where 'when' could be more explicit or specific rather than the fully-triggered 5.

4 / 5

Trigger Term Quality

Natural phrases like "sync docs to code changes", "translation drift", and "documentation maintenance" are what a user would plausibly say. Not 5 because common variations are missing: "broken links", "out-of-date docs", "readme", "markdown", or file extensions; not 3 because coverage clearly goes beyond a couple of generic keywords with several relevant domain terms.

4 / 5

Distinctiveness Conflict Risk

The niche (repo doc verification, diff-based sync, translation drift) is fairly distinct with specific triggers, matching "mostly distinct; minor overlap risk". Minor overlap remains with general code-review and translation skills, which the body disambiguates via 'oma-translation' routing but the description alone does not fully separate.

4 / 5

Total

16

/

20

Passed

Validation

93%

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

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

relative_links

Relative link issues: 2 missing

Warning

Total

15

/

16

Passed

Repository
first-fluke/oh-my-agent
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.