CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

code-understanding

Provides adversarial code comprehension for security research, mapping architecture, tracing data flows, and hunting vulnerability variants to build ground-truth understanding before or alongside static analysis.

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 ./.claude/skills/code-understanding/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

71%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 a lean, well-structured operational document with strong actionability — exact flags, output schemas, formats, and gate checkpoints — and only minor redundancy between the execution rules and gates. Its main weakness is progressive disclosure: it repeatedly defers to stage-specific files (map.md and unspecified 'stage-specific files') that are absent from the bundle, and the Study mode from the Modes table is missing from the Stages table.

Suggestions

Either include the stage-specific files (map.md, etc.) in the bundle or replace the dangling references with self-contained instructions; if the files exist at runtime, reference them as resolvable paths/links rather than bare names.

Add the Study and Teach rows (or note why they are absent) to the Stages table so the mode → gate → output mapping is complete and consistent with the Modes table.

Remove the duplicate framing — the intro paragraph repeats the description verbatim and several execution rules restate GATEs (rule 2/GATE-U5, rule 4/GATE-U4) — and clarify what 'output_dir: resolved by raptor-run-lifecycle' concretely means for the operator.

DimensionReasoningScore

Conciseness

The body is dense and operational — tables for modes and stages, no tutorials on concepts Claude already knows — but the opening paragraph repeats the frontmatter description almost verbatim, the execution rules and GATEs partially restate each other (e.g. rule 4 vs GATE-U4, rule 2 vs GATE-U5), and the runtime-probe section is wordier than needed. Not 5 due to this duplicated material; not 3 because the padding is minor, not whole unnecessary sections.

4 / 5

Actionability

Concrete, executable guidance throughout: exact command flags (--map, --trace <entry>), exact file-reference and flow formats, named JSON outputs (context-map.json, flow-trace-<id>.json, variants.json), and a precise checklist-item schema table. As an instruction-only skill the absence of code is not penalized. Not 5 because some operational details are unresolved in-body ('output_dir: resolved by raptor-run-lifecycle' defers a value without a pointer, and how/where the modes are invoked is never shown); not 3 because the guidance goes well beyond high-level hints.

4 / 5

Workflow Clarity

The Stages table cleanly sequences mode → gates → output, the execution rules are numbered, and the gates act as explicit checkpoints (READ-FIRST, EVIDENCE-ONLY confidence matching is effectively a validation gate). Not 5 because there is no explicit feedback/error-recovery loop and the Stage table omits Study (which appears in the Modes table), leaving a minor gap; not 3 because checkpoints are explicit and the sequence is coherent.

4 / 5

Progressive Disclosure

The body is well-sectioned and explicitly defers detail ('See stage-specific files for detailed instructions', 'MAP-7 in map.md'), but the bundle contains no stage-specific files — no references/, scripts/, or assets/ exist, and map.md is referenced by name without a path or link, so the signaled references dangle. Per the guideline to score against the actual bundle structure, the clearly-signaled one-level references point at files that are not present, leaving navigation broken despite good in-file organization. Not 2 because the SKILL.md itself is appropriately split and the references are clearly signaled, not buried; not 4 because referenced files cannot actually be reached.

3 / 5

Total

15

/

20

Passed

Description

58%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 communicates a clear and fairly distinctive capability with concrete actions, but it reads as a domain summary rather than a trigger-optimized description: it lacks any explicit 'use when' guidance and omits the natural phrases a user would say when needing it. Adding a trigger clause with plain-language synonyms would lift completeness and trigger-term quality.

Suggestions

Append an explicit trigger clause, e.g. 'Use when analyzing an unfamiliar codebase for security research, when a finding needs its data flow traced from untrusted input to a sink, or when hunting variants of a known vulnerable pattern.'

Include natural user phrasings as trigger terms ('understand this codebase', 'trace this input', 'find other places like this', 'attacker's view') instead of jargon-only terms like 'adversarial code comprehension'.

Trim the abstract closer ('to build ground-truth understanding') in favor of one more concrete action, e.g. extracting invariants and contracts from a subsystem.

DimensionReasoningScore

Specificity

Names the domain ('security research') and several concrete actions — 'mapping architecture, tracing data flows, and hunting vulnerability variants' — which is several specific actions with minor gaps ('build ground-truth understanding' is more abstract than an action). Not 5 because the closing purpose phrase is abstract and coverage of the modes (study/teach) is not indicated; not 3 because the action list clearly exceeds 1-2 concrete actions.

4 / 5

Completeness

The 'what' is clear (map architecture, trace data flows, hunt variants), but there is no 'Use when...' clause; the only temporal hint is 'before or alongside static analysis', which weakly implies when. The judging guideline caps completeness at 3 for a missing explicit trigger clause; not 2 because the 'what' is concrete, not vague.

3 / 5

Trigger Term Quality

Relevant keywords exist ('architecture', 'data flows', 'vulnerability variants', 'static analysis') but common natural variations are missing — no 'understand this codebase', 'audit', 'trace this input', 'taint', or file-type hints. Not 4 because a user needing code comprehension would not naturally say 'adversarial code comprehension' or 'ground-truth understanding'; not 2 because several genuinely relevant domain terms are present.

3 / 5

Distinctiveness Conflict Risk

The niche (adversarial comprehension for security research complementing static analysis) is fairly distinct from general code-review or document skills. Not 5 because it could still overlap with generic 'understand/analyze this code' requests or a security-review skill given no explicit trigger scoping; not 3 because the security-research framing and pre-scan positioning give it a clear niche.

4 / 5

Total

14

/

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

gadievron/raptor

Path

.claude/skills/code-understanding/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.