code-understand

Build a ranked, citation-backed focus map of a codebase — the files and symbols an architecture actually hangs on — using CodeGraph when available and a dependency-free builtin (regex AST extraction + `rg` cross-file references) otherwise. Use this any time you (the coding agent) need to orient in an unfamiliar or large codebase before making a change: the user says "help me understand this codebase", "what's load-bearing here", "what would break if I change X", "who calls this", "map out this project's architecture", or you're about to touch code you haven't read yet and want to know what matters before scanning everything by hand. This is the same extractor `wiki-update` Step 3b uses internally — this skill exposes it directly so any agent session can call it on demand, not just during a wiki sync.

Quality

80%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

75%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 tight, actionable single-command skill body with clear sections, a failure fallback, and concrete interpretation guidance. Minor trimming and a worked example invocation would push it higher.

Suggestions

Add one complete example invocation with realistic values (e.g. `obsidian-wiki code-understand --project . --since HEAD~5 --pretty`) to make the actionability fully copy-paste ready.

Trim the opening paragraph and the 'map, not a substitute' aside to tighten conciseness.

Dimension	Reasoning	Score
Conciseness	Mostly efficient operational prose with no padding about concepts Claude already knows, though the intro paragraph and a few explanatory sentences ('This is a map, not a substitute for reading the actual code it cites') could be trimmed.	4 / 5
Actionability	Provides a copy-paste-ready command with every flag documented and a worked `--since HEAD~5` example plus an install command, but lacks a full end-to-end example invocation with real values.	4 / 5
Workflow Clarity	Clear run-then-interpret sequence with an explicit GUARD checkpoint for command failure and a numbered 'Reading the output' guide; no destructive/batch operation, so the cap-3 rule does not apply.	4 / 5
Progressive Disclosure	Well-organized into clear sections (When to reach, Running it, Reading the output, If CodeGraph isn't installed) with no bundle files to reference; slightly over the 50-line simple-skill threshold so it stops just short of 5.	4 / 5
	Total	16 / 20 Passed

Description

86%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, trigger-rich description that clearly states what it does and when to use it, with excellent natural-language triggers. The main weakness is second-person voice, which triggers the specificity penalty.

Suggestions

Rewrite in third person ('Builds a ranked... use when the agent needs to orient...') to avoid the second-person specificity penalty.

Drop or tighten the trailing provenance sentence about `wiki-update` Step 3b — it adds length without aiding trigger matching.

Dimension	Reasoning	Score
Specificity	Names a concrete action ('Build a ranked, citation-backed focus map') and the mechanism (CodeGraph or a regex AST + `rg` builtin), which is solidly a 4, but the description uses second person ('you (the coding agent) need to orient', 'you're about to touch code'), which per the guidelines reduces specificity by 1.	3 / 5
Completeness	Explicitly answers both what (build a ranked, citation-backed focus map of load-bearing symbols) and when ('Use this any time you... need to orient'), backed by concrete trigger phrases.	5 / 5
Trigger Term Quality	Quotes several natural user phrases verbatim — 'help me understand this codebase', 'what's load-bearing here', 'what would break if I change X', 'who calls this', 'map out this project's architecture' — giving comprehensive coverage of how users actually ask for this.	5 / 5
Distinctiveness Conflict Risk	Has a clear niche (on-demand architecture focus map via a specific extractor) and even distinguishes itself from `wiki-update`, but 'help me understand this codebase' is broad enough to risk mild overlap with general code-exploration skills.	4 / 5
	Total	17 / 20 Passed

Validation

100%

Warnings & errors only

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: Ar9av/obsidian-wiki
Path: .skills/code-understand/SKILL.md
Commit: 58aba18

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

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.