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

75%

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

Fix and improve this skill with Tessl

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

Quality

Content

70%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 dense, well-sequenced orchestration skill with excellent workflow clarity — explicit validation gates, bounded retry loops, and complete failure/exit paths. Its weaknesses are notable cross-section repetition that inflates token cost, and references to resource files that are not present in the shipped bundle.

Suggestions

State each recurring rule once — the archify sidecar contract and the code_intelligence/native-search fallback are each repeated 3-4 times across Scheduling, Structural Flow, Logical Operations, and Guardrails; consolidate to one section plus a short pointer.

Collapse the three resource listings (Dependencies, Tools and instruments, References) into a single section; the Actions/SSL-primitive table largely restates the Scenes and could be merged.

Ship the referenced files (`resources/draft-format.md`, `resources/document-structure.md`, `resources/html-contract.md`) inside the skill bundle, or inline the minimal draft syntax example so the skill is self-contained when the `oma` resources are unavailable.

DimensionReasoningScore

Conciseness

Individually the prose is terse — no concept explanations, no fluff — but the same facts repeat across the house-format sections: the archify sidecar rules appear in four places (Expected outputs, Control-flow features, DELIVER, Guardrail 6), the code_intelligence fallback caveat three times (Dependencies, COLLECT, Tools), and the resource list three times (Dependencies, Tools and instruments, References). This matches 'mostly efficient but could be tightened' rather than the trimmable-only-minor-instances of a 4; it does not reach the padded/generic-explanation level of a 2.

3 / 5

Actionability

Concrete, executable guidance throughout: exact commands (`git diff --cached`, `git diff main...{branch}`, `gh pr diff`, `oma explain render`, `oma explain validate [file]`), a deterministic ref resolution order, exact output paths (`.agents/results/explain/{YYYY-MM-DD}-{slug}.html`), and template selectors (`template: doc` / `sheet`). Minor gaps — no example draft snippet and the draft syntax is deferred to an external resource — keep it below the fully copy-paste-ready 5.

4 / 5

Workflow Clarity

The Scenes section gives a clearly sequenced RESOLVE → COLLECT → GATE → GENERATE → VALIDATE → DELIVER pipeline with explicit validation checkpoints (dual secret gates, deterministic grep checklist), a bounded fix-retry feedback loop (max 3 iterations), transitions, per-failure recovery paths, and defined exit criteria. This matches the top anchor: clear sequence, explicit validation, feedback loops, and a checklist.

5 / 5

Progressive Disclosure

References are clearly signaled, purpose-annotated, and one level deep (`resources/draft-format.md`, `document-structure.md`, `html-contract.md`), but none of the referenced files exist in the bundle — no references/, scripts/, or assets/ directories are present, and the paths point into an external `oma` system (`.agents/workflows/explain.md`, `_shared/conditional/diagram-engine.md`). Scored against the actual bundle structure, the navigation chain is broken for a standalone reader, which fits 'some structure but could be better organized' rather than the 4 whose references resolve.

3 / 5

Total

15

/

20

Passed

Description

70%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 clear, concise, third-person description that answers both what and when with reasonably natural trigger terms. Its weaknesses are a single listed action and a 'when' clause that omits the most natural trigger phrasing ('explain this PR/change'), leaving it just short of the top anchors.

Suggestions

List one or two more concrete actions (e.g., 'with a comprehension-ordered code walkthrough and quiz') so the 'what' enumerates several specific capabilities rather than one.

Broaden the 'Use when' clause to cover the natural requests, e.g., 'Use when asked to explain or walk through a PR, diff, or branch, or when a visual/HTML walkthrough of a topic is requested.'

DimensionReasoningScore

Specificity

The description names the domain ('offline HTML explanation') and the concrete target types ('code change (diff, PR, branch)', 'topic, system, or question'), but lists only one action — creating an explanation document. Score 4 requires several specific actions (e.g., extract, fill, merge), and this stays at one verb applied to multiple inputs; score 2's generic single action ('Processes PDF files') understates the precision of the target enumeration.

3 / 5

Completeness

Both halves are explicit: what — 'Create an offline HTML explanation of a code change... or of a topic, system, or question'; when — 'Use when a visual walkthrough document is requested.' The 'when' clause is present and concrete but somewhat narrow — it does not mention the natural case of asking to explain a PR/change — so it matches 'both present, when could be more explicit' rather than the fully concrete trigger phrasing of a 5.

4 / 5

Trigger Term Quality

Natural terms users would say are present: 'diff', 'PR', 'branch', 'explanation', 'visual walkthrough document'. Common variations such as 'explain', 'explainer', 'onboarding', or 'walk me through' are missing, which fits the 'good keyword coverage; a few natural terms missing' anchor rather than the comprehensive synonym coverage of a 5.

4 / 5

Distinctiveness Conflict Risk

'Offline HTML explanation' and 'visual walkthrough document' carve a clear niche distinct from docs, slides, or video skills, with minimal conflict risk on the change-mode triggers. The 'topic, system, or question' clause is broad and could overlap with general documentation/answer skills, keeping it at 'mostly distinct; minor overlap risk' rather than the minimal-conflict 5.

4 / 5

Total

15

/

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

.agents/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.