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.

61

Quality

72%

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

Fix and improve this skill with Tessl

tessl review fix ./.agents/skills/oma-docs/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

77%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 efficient, well-sequenced operations manual with concrete commands, explicit validation checkpoints, and a genuine error-recovery table — workflow clarity is excellent. Its one real defect is structural: the skill leans on `resources/commands.md` for flags and outputs, but that file (and any bundle directory) is absent, so the promised progressive-disclosure layer does not exist.

Suggestions

Ship the referenced `resources/commands.md` in the bundle (or inline the essential flags and output-file locations for each mode) so the repeated "Read resources/commands.md" pointers resolve.

Add one concrete `oma docs sync` example with a real range (e.g. `oma docs sync HEAD~3..HEAD --json`) to remove the `<range>` ambiguity.

Tighten the verbose first row of the failure-and-recovery table; its three clauses could be one instruction plus a one-line labeling rule.

DimensionReasoningScore

Conciseness

The body is dense and operational — no explanations of concepts Claude already knows, every section carries instructions (e.g. "Run `oma docs verify --json`, `oma docs sync <range> --json`..."). It is not a 5 because a few passages could still be tightened, notably the long first failure-table cell ("Label the result 'manual inspection — `oma docs verify` did not run'; never present it as CLI output and never make installing the CLI a prerequisite").

4 / 5

Actionability

Concrete commands are given for all four modes (`oma docs verify --json`, `oma docs sync <range> --json`, `oma docs i18n --json`, `oma docs lint --json`) with a concrete fallback range ("staged changes, then `HEAD~1..HEAD`") and a fully specified manual fallback ("extract `[text](path)`, `![alt](path)`, and `href`/`src` targets"). Not a 5 because flag details live in the referenced resources/commands.md and `<range>` syntax is never shown with a real example, leaving minor gaps.

4 / 5

Workflow Clarity

The five-step canonical path is clearly sequenced with explicit validation checkpoints and a feedback loop: step 3 ("Verify each proposed correction against current code"), step 5 ("Re-run affected checks after edits and record remaining failures"), plus a failure-and-recovery table covering missing CLI, failed patches, and failed index writes. This matches 'Clear sequence with explicit validation steps; feedback loops for error recovery' — the batch-edit operation does have validation, so the batch cap does not apply.

5 / 5

Progressive Disclosure

Sections are well organized and the References list is clearly signaled and one level deep, but the body repeatedly delegates operational detail to `resources/commands.md` ("Read `resources/commands.md` for flags and output files"), and no bundle exists — no references/, scripts/, assets/, or resources/ directory is present, so the primary referenced file is dangling. Per the guideline to score against the actual bundle structure, navigation fails at the first hop, which sits between 'references present but not clearly signaled' (3) and 'references mostly clear' (4); the missing file pulls it to 3.

3 / 5

Total

16

/

20

Passed

Description

67%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, two-sentence structure with an explicit 'Use for...' clause and three named capabilities. Its main weakness is trigger-term breadth: it lacks the everyday synonyms (broken links, stale docs, localization) that would make it reliably surface, and the when-clause is broader than the skill's actual niche.

Suggestions

Add natural trigger synonyms such as 'broken links', 'stale or outdated docs', 'localization', and 'i18n' so the description matches the phrases users actually say.

Make the 'when' clause more concrete, e.g. 'Use when the user mentions broken doc links, docs out of sync with a code change, or translations drifting from the source text.'

Mention the fourth capability (linting localized prose / i18n style checks) so the what-clause covers all four modes the skill supports.

DimensionReasoningScore

Specificity

Quotes three concrete actions — "Check documentation references", "sync docs to code changes", "detect translation drift" — which matches the anchor 'Lists several specific actions; minor gaps in coverage'. Not a 5 because the fourth mode (lint/style checking of localized prose) and URL verification are absent, so coverage is not comprehensive.

4 / 5

Completeness

Both parts are explicit: the what ("Check documentation references, sync docs to code changes, and detect translation drift") and the when ("Use for documentation maintenance in a repository"). Matches 'Has both what and when; when could be more explicit or specific' — the when-clause is generic ('documentation maintenance') rather than concrete trigger phrases, keeping it below 5.

4 / 5

Trigger Term Quality

Relevant keywords exist ("documentation references", "sync docs", "code changes", "translation drift") but common natural variations users would say — e.g. "broken links", "stale/outdated docs", "localization" — are missing, matching 'Some relevant keywords but missing common variations or synonyms'. Not a 4 because the natural-phrase coverage is thin beyond the word "docs".

3 / 5

Distinctiveness Conflict Risk

The docs-verification/sync/translation-drift niche is mostly distinct with minor overlap risk against general writing or translation skills, matching 'Mostly distinct; minor overlap risk with closely related skills'. Not a 5 because 'documentation maintenance' as the trigger phrase is broad enough to compete with generic docs/writing skills.

4 / 5

Total

15

/

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.