CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

oma-explanation

Create an offline HTML explanation of a code change (diff, PR, branch) or of a topic, system, or question. Use when a visual walkthrough document is requested.

Quality

81%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

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.

A well-architected orchestration body: the multi-mode workflow is sequenced with explicit validation gates, bounded fix loops, and honest failure/exit states, and all heavy detail is properly pushed to purpose-labeled resource files. The main cost is redundancy — the same resources, tools, and scheduling facts are restated across the Scheduling, Structural Flow, and Logical Operations sections, which inflates token cost without adding guidance.

Suggestions

Collapse the triple listing of resources (Dependencies, Tools and instruments, References) into one canonical list; the Actions table and prose also restate the same git/gh/code_intelligence facts.

Let the Scenes reference the Scheduling parameters (reader level, language, quiz count) instead of redefining them in Entry, so each fact is stated once.

Inline a minimal three-line draft example (or the `oma explain components` output) so the core GENERATE step is executable without opening the external draft-format resource.

DimensionReasoningScore

Conciseness

The body is dense and teaches nothing Claude already knows, but carries real duplication: the same resource files are listed three times ("Dependencies", "Tools and instruments", "References"), git/gh and the code_intelligence fallback are restated in both Actions tables and prose, and Scenes largely restate the Scheduling section (reader level, language, quiz count appear in both "Expected inputs" and Entry step 3). This is more than the minor trimmable instances of the 4 anchor, though well short of padded verbosity.

3 / 5

Actionability

Concrete copy-paste commands throughout — `git diff main...{branch}`, `gh pr diff`, `git diff --cached`, `oma explain render`, `oma explain validate [file]` — plus exact output paths, a four-step ref-resolution order, and hard iteration limits. The one gap is that the core authoring artifact (the draft syntax) is entirely delegated to `resources/draft-format.md` with no inline example, so guidance is mostly rather than fully executable from the body alone.

4 / 5

Workflow Clarity

A clear sequence (Entry → RESOLVE/COLLECT/GATE/GENERATE/VALIDATE/DELIVER → Exit) with explicit validation checkpoints and feedback loops: dual secret gates, "Fix → re-validate, max 3 iterations; then surface failures and stop", per-failure recovery paths, and defined success/partial/failed exit states. This matches the top anchor's validate-fix-retry-with-checklist profile exactly.

5 / 5

Progressive Disclosure

The body is an overview that delegates the heavy detail one level deep with each file's purpose labeled ("the draft you write and the `oma explain render` commands", "WHAT a change explainer contains", "HOW the HTML behaves and is validated"), consolidated again in a final References section. No bundle files exist alongside this SKILL.md, but the body's own structure is a clean overview with well-signaled, one-level-deep pointers and easy navigation.

5 / 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 tight, specific description that names the artifact (offline HTML explanation), both input modes, and an explicit use-when trigger, with no fluff or over-claims. It is solidly above midpoint on every dimension but stops short of top anchors: the trigger list and when-clause each cover one phrasing rather than the fuller set of natural user phrases.

Suggestions

Broaden the 'Use when' clause with concrete trigger phrasings users actually say, e.g. "Use when the user asks to explain/walk through a diff, PR, branch, or commit range, or wants a visual explainer of a topic or question".

Add one or two artifact-level specifics (e.g. "with diagrams and a comprehension quiz") so the 'what' covers the produced experience, not just the file type.

Include synonyms such as "explainer", "walkthrough", or "commit range" to widen natural trigger coverage without adding length.

DimensionReasoningScore

Specificity

"Create an offline HTML explanation" is a concrete action and the input surface is enumerated ("diff, PR, branch", "topic, system, or question"), covering both modes with only minor gaps — it never mentions the walkthrough/quiz/panels the artifact contains, so it falls between the 1-2-actions anchor (3) and comprehensive coverage (5), noticeably above the midpoint.

4 / 5

Completeness

Both what ("offline HTML explanation of a code change ... or of a topic, system, or question") and when ("Use when a visual walkthrough document is requested") are explicitly present. The when-clause is a single, somewhat self-referential condition rather than the multiple concrete user trigger phrases of the 5 anchor, so it sits at the 4 anchor.

4 / 5

Trigger Term Quality

Good natural keyword coverage: "explanation", "visual walkthrough", "diff", "PR", "branch", "HTML", "topic", "question". A few natural phrases users would say are missing ("explain this PR", "commit range", "explainer", "how does X work"), which matches the good-coverage-with-gaps anchor rather than the comprehensive synonym/extension coverage of 5.

4 / 5

Distinctiveness Conflict Risk

"offline HTML explanation" plus the diff/PR/branch/topic scoping carves a clear niche with distinct triggers, giving mostly-distinct behavior with only minor overlap risk against generic documentation or presentation skills; judged on the description alone it does not fully lock in the minimal-conflict profile of 5.

4 / 5

Total

16

/

20

Passed

Validation

100%

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

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