CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

understand-issue

Investigate a GitHub issue or reported bug the way a seasoned maintainer would — form an independent model before reading the thread's theories, trace the mechanism and history, verify the diagnosis, and return a concise briefing with a verdict and fix direction. Use for triage, root-cause analysis, or re-investigation.

Quality

91%

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

92%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-structured instruction skill: a clear sequenced workflow with verification gates and posting approval, concrete verdicts and record contracts, and executable detail correctly split into one-level-deep reference files that exist in the bundle. The only real cost is mild redundancy between the principles section and the numbered sections.

DimensionReasoningScore

Conciseness

The body is dense, assumes competence, and never explains basics Claude already knows, but there is measurable redundancy: the "What matters" principles are restated across sections 1, 6, and "Tone", and lines like "The gap between your model and theirs exposes anchoring in both directions" are framing rather than instruction. Not score 5 (every token does not earn its place) and not score 3 (there is no unnecessary explanation or padding of known concepts).

4 / 5

Actionability

For an instruction-only skill the guidance is fully actionable: an exact record path (`.mastracode/scratch/issues/<owner>-<repo>-<n>.md`), a closed verdict taxonomy with literal strings, branch-name patterns to infer the issue, per-branch deeper checks, and executable commands one level deep in `references/recipes.md` pointed to at each step. Not score 4 because there are no minor gaps — the common cases (resolve issue, trace symptom, history, regression, probe, posting) are all covered concretely.

5 / 5

Workflow Clarity

A clear six-step sequence (build model → read thread → diagnose → history → verify → decide and brief) with explicit validation checkpoints: falsification-based verification, "Never claim a reproduction you did not run", an approval gate for posting ("Show the draft; wait for the go"), and a re-investigation loop. The destructive/outward-facing operation (GitHub posting) has validation, so no cap applies.

5 / 5

Progressive Disclosure

The body is an overview and all executable detail lives one level deep in the existing `references/recipes.md` and `references/templates.md`, each clearly signaled at the exact point of use ("Resolve the issue with the minimal recipe in `references/recipes.md`", "Use `references/templates.md` as an example, not a schema"). Not score 4 because there is no inline content that should have been split out and navigation is unambiguous.

5 / 5

Total

19

/

20

Passed

Description

88%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 strong description: it states a concrete multi-step capability, uses an explicit 'Use for...' trigger clause, and carves out a recognizable niche. Trigger coverage is good but misses a few common synonyms (diagnose, debug), and "reported bug" creates minor overlap risk with generic debugging skills.

DimensionReasoningScore

Specificity

Multiple concrete actions are listed — "form an independent model before reading the thread's theories, trace the mechanism and history, verify the diagnosis, and return a concise briefing with a verdict and fix direction" — comprehensively covering the investigation workflow. It is not score 4 because coverage is comprehensive rather than having minor gaps; not below 5 since no action is vague.

5 / 5

Completeness

Both what ("Investigate a GitHub issue or reported bug... trace the mechanism and history, verify the diagnosis, and return a concise briefing with a verdict and fix direction") and when ("Use for triage, root-cause analysis, or re-investigation") are explicitly and clearly stated. Score 4 would require the when to be less explicit; here concrete trigger phrases are present.

5 / 5

Trigger Term Quality

Good natural keywords: "GitHub issue", "reported bug", "triage", "root-cause analysis", "re-investigation" — phrases users would actually say. It is not 5 because common synonyms like "diagnose", "debug", or "dig into this issue" are absent, but well above anchor 3 since multiple natural trigger phrases are present.

4 / 5

Distinctiveness Conflict Risk

The niche is clear — maintainer-style GitHub issue investigation with a verdict — and triggers like "triage" and "root-cause analysis" are distinct. Minor overlap risk remains with generic debugging and PR-review skills triggered by "reported bug"; it is not 5, but far more distinct than the "somewhat specific" anchor 3.

4 / 5

Total

18

/

20

Passed

Validation

87%

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

Validation — 14 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

metadata_field

'metadata' should map string keys to string values

Warning

Total

14

/

16

Passed

Repository

mastra-ai/mastra

Path

.mastracode/skills/understand-issue/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.