CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

oma-docs

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

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

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 well-engineered instruction-only skill: executable CLI commands with defaults, a numbered workflow with pre- and post-edit validation, and a concrete manual fallback for every failure mode. The main weaknesses are mild redundancy and a few overloaded sentences, plus a referenced bundle file (resources/commands.md) that is not actually present in the bundle.

Suggestions

Include resources/commands.md in the skill bundle — it is referenced three times as the source of mode flags and outputs but does not exist in the provided files.

Split the dense 'Missing CLI' table row and step 4 into shorter lines or sub-steps so the fallback procedure and the docs.sync-patch-approval recording are easier to follow.

Show one concrete example of a docs.sync-patch-approval record (fields and values) instead of deferring entirely to 'workflow Step 4 owns the command template'.

DimensionReasoningScore

Conciseness

The body is dense and operational — no space is spent explaining concepts Claude already knows, and the failure/recovery table packs actionable detail compactly. Not 5: there is slight redundancy (the pointer to resources/commands.md appears in Dependencies, References, and step 1) and a few overloaded run-on sentences (the 'Missing CLI' table row, step 4) that could be tightened; not 3: there is no unnecessary explanation or padding.

4 / 5

Actionability

Gives verbatim commands (`oma docs verify --json`, `oma docs sync <range> --json`, `oma docs i18n --json`, `oma docs lint --json`), concrete default diff ranges (staged, then `HEAD~1..HEAD`), named output files (docs/generated/doc-refs.json, url-drift.json), and an executable manual fallback (extract `[text](path)`, `![alt](path)`, href/src). Not 5: the docs.sync-patch-approval recording step defers its command template to an external workflow ('workflow Step 4 owns the command template'), leaving a gap; not 3: the guidance is executable, not pseudocode.

4 / 5

Workflow Clarity

The canonical command path is a clear 5-step sequence with explicit validation before edits ('Verify each proposed correction against current code and document context'), a feedback loop after edits ('Re-run affected checks after edits and record remaining failures'), a failure/recovery table covering five failure modes, and defined exit criteria. This matches the top anchor's explicit validation, error-recovery feedback loops, and checklists; the validation present also avoids the destructive/batch cap.

5 / 5

Progressive Disclosure

The body stays lean and pushes mode-specific flags to a clearly signaled, one-level-deep reference with scoped reading guidance ('Read only the matching section of resources/commands.md'), and the References section annotates each link's purpose. Not 5: the referenced resources/commands.md file is not present in the provided bundle (no resources/ directory exists), and cross-skill references (../oma-translation/SKILL.md, ../_shared/core/execution-policy.md) depend on external layout, so the bundle structure cannot fully support navigation; not 3: references are clearly signaled and content is appropriately split rather than inlined.

4 / 5

Total

17

/

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.

A solid description that states three concrete capabilities and includes an explicit use-when clause in third person. It sits just below the top tier because the 'when' clause is generic and natural trigger synonyms (broken links, outdated docs, localization) are absent.

Suggestions

Make the 'when' clause concrete with trigger phrases, e.g., "Use when the user mentions broken doc links, outdated or stale documentation after code changes, or inconsistent translations."

Add natural synonyms such as 'outdated docs', 'broken links', 'localization/i18n', and '.md files' to broaden trigger coverage without adding length.

DimensionReasoningScore

Specificity

"Check documentation references", "sync docs to code changes", and "detect translation drift" name three distinct concrete actions in the documentation domain. Not 5: the first action is less granular than the top anchor's level of detail and coverage has minor gaps (e.g., the lint/style mode is omitted); not 3: it goes beyond the 1-2 concrete actions of the midpoint anchor.

4 / 5

Completeness

The 'what' is explicit (check references, sync docs to code changes, detect translation drift) and a 'Use for...' clause provides the 'when' ("Use for documentation maintenance in a repository"), mirroring anchor 4's example. Not 5: the 'when' is generic and lacks concrete trigger phrases (e.g., 'when the user mentions broken links or outdated docs'); not 3: the 'when' is explicitly stated, not merely implied.

4 / 5

Trigger Term Quality

Natural terms include "documentation", "docs", "code changes", and "translation drift" — phrasing users would plausibly use. Not 5: common synonyms and variations are missing ("broken links", "outdated/stale docs", "localization", ".md"); not 3: coverage is well beyond the 'some relevant keywords' anchor.

4 / 5

Distinctiveness Conflict Risk

The combination of reference checking, diff-based doc syncing, and translation drift detection carves a mostly distinct repository-docs niche with minor overlap risk against general writing or translation skills. Not 5: "documentation maintenance in a repository" remains broad enough to overlap with closely related skills; not 3: the three named capabilities are far more specific than 'Works with document files'.

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

Path

.agents/skills/oma-docs/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.