Codebase understanding

Skill HelloThisWorld/agent-skill-verification-template/skills/codebase-understanding

Production-oriented template for building AI agent skills as verifiable software components — offline eval harness, source-grounding validators, structured logs/traces/metrics, replay artifacts, and a CI quality gate. Runs fully offline with a deterministic mock model.

Install

npx -y skills add HelloThisWorld/agent-skill-verification-template --skill codebase-understanding

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Answers questions about a codebase using source-grounded evidence. Every factual claim must cite a specific file and line; ambiguous or unsupported questions return insufficient_evidence instead of a guess.

SKILL.md

2.4 KB, as published. Nobody here has run it

Codebase Understanding

A Claude-style skill that answers natural-language questions about a codebase and backs every claim with file:line evidence. It is designed to be verified like a production component — see skill-contract.json for the machine-readable contract and verification-rules.md for how outputs are graded.

When to use

Use this skill to answer questions such as "Which component publishes UserCreatedEvent?" or "Which file handles payment authorization?" against a known repository (here, the fixture repo under fixtures/sample-repo).

Tools

Tool	Purpose
`repo_search`	Case-insensitive substring search. Returns `{file, line, text}` matches.
`read_file`	Read a file by repo-relative path to confirm evidence.

Contract rule: repo_search must be used before read_file.

Procedure

Identify the key symbols/keywords in the question.
Use repo_search to locate candidate evidence.
Use read_file to confirm the strongest candidate.
Produce a structured answer where every claim cites a real file:line.
If the evidence is missing or ambiguous, return insufficient_evidence with an empty claims array. Never invent an answer or a citation.

Output contract

The skill must return JSON with:

status: answered | insufficient_evidence | refused
answer: a short natural-language answer
claims: array of { text, citations: [{ file, line }] }
toolCalls: array of { tool, arguments }
confidence (optional): low | medium | high

See examples.md for concrete input/output pairs.

Design note: contract vs. model

This SKILL.md and the contract are model-independent — they describe what a correct answer looks like. How reliably a given model satisfies the contract (pass rate, latency, cost, failure modes) is measured separately by the eval harness and will differ per model. The offline mock adapter is a reference implementation that satisfies the contract deterministically.