CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

codebase-understanding

Build an evidence-based mental model of an unfamiliar existing repository: structure, ownership, flows, entry points, and change locations. Use for onboarding, tracing, and discovery before another task. Do not use to prescribe a design, issue findings, implement changes, or diagnose a specific failure.

Quality

85%

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

85%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, highly actionable instruction skill with an excellent sequenced workflow, built-in evidence-validation checkpoints, and copy-paste output templates. Its two real weaknesses are dangling references — the entire shared/ policy layer and workflow contract are linked but absent from the bundle — and moderate redundancy in the routing-boundary material.

Suggestions

Ship the referenced shared/base/*.md policy files and shared/workflow-contract.md in the bundle, or remove/inline the "Required packaged policies" and "Optional Workflow Integration" sections so no link points to a nonexistent file.

Consolidate the routing boundary into one place: the "Routing Boundary" section repeats the frontmatter description and the "Purpose and activation" disambiguation list, and can be merged.

Move the two full output-contract templates (roughly 50 lines) into a references file (e.g. references/report-templates.md) to slim the main body, keeping only a short pointer and one table-schema example inline.

DimensionReasoningScore

Conciseness

The body is telegraphic and assumes Claude's competence throughout — no concept explanations, no padding, every section is instruction. It stays at 4 rather than 5 because the routing boundary is stated three times (frontmatter description, "Purpose and activation", and the "Routing Boundary" section) and the boilerplate "Base Framework"/"Optional Workflow Integration" sections add tokens that do not each earn their place.

4 / 5

Actionability

For an instruction-only skill the guidance is fully actionable: a concrete 5-step workflow with named artifact types (manifests/locks, Docker/CI, migrations/schema), a copy-paste-ready output contract with exact headers and table schemas (| Module | Responsibility | Key Files | Dependencies | Confidence |), specific clarifying questions, and worked cases in modes-and-examples.md. Scored 5 per the instruction-only carve-out since the specific guidance covers the common cases; a 4 would imply missing key execution details, which are not missing.

5 / 5

Workflow Clarity

The workflow is a clearly sequenced 5-step process (reconnaissance → entry points → flow tracing → cross-cutting maps → risk/next action) with an explicit validation mechanism (VERIFIED/INFERRED/UNKNOWN classification with confidence levels), an end-of-task Quality checklist, and a defined fallback when no repository is supplied. The skill is read-only analysis, so the destructive/batch validation cap does not apply.

5 / 5

Progressive Disclosure

The three references/ files are real, well-signaled, one level deep, and appropriately split (reconnaissance.md, flow-tracing.md, modes-and-examples.md). However, scoring against the actual bundle, 10 of the 13 referenced paths are dangling: the nine shared/base/*.md policy links and shared/workflow-contract.md do not exist in the bundle, so a large fraction of the declared navigation structure fails. This is worse than the minor organization gaps of a 4 but better than a 2, since the structure and signaling that do exist are good.

3 / 5

Total

17

/

20

Passed

Description

80%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 with an explicit what/when pair and excellent boundary discipline against neighboring skills. The main weakness is trigger-term coverage: it relies on abstract labels (tracing, discovery) and misses the concrete phrases a user would most naturally say when they need codebase understanding.

Suggestions

Add natural user phrasings to the trigger clause, e.g. "Use when the user asks to understand or explain a codebase, find where a feature is implemented, onboard to a repository, or trace a request/auth/data flow."

Consider naming concrete artifacts users mention (README, monorepo, legacy app) as trigger synonyms alongside the abstract terms.

DimensionReasoningScore

Specificity

The description enumerates concrete deliverables — "structure, ownership, flows, entry points, and change locations" — with only minor coverage gaps. It stays at 4 rather than 5 because everything hangs off a single macro-action ("Build an evidence-based mental model") rather than multiple distinct concrete action verbs, and it is not at 3 because five specific objects of the model are named.

4 / 5

Completeness

It explicitly answers both parts: the "what" ("Build an evidence-based mental model of an unfamiliar existing repository: structure, ownership, flows, entry points, and change locations") and the "when" ("Use for onboarding, tracing, and discovery before another task"), plus a negative boundary ("Do not use to prescribe a design, issue findings, implement changes, or diagnose a specific failure"). This matches the top anchor with concrete trigger phrases; a 4 would require the "when" clause to be less explicit, which it is not.

5 / 5

Trigger Term Quality

"Use for onboarding, tracing, and discovery" supplies some relevant keywords, with "onboarding" being genuinely natural user language. It sits at 3 rather than 4 because the most common phrasings users would actually say — "understand this codebase", "explain this architecture", "where is X implemented", "get up to speed" — are absent, and "tracing"/"discovery" read as skill-author vocabulary more than user vocabulary.

3 / 5

Distinctiveness Conflict Risk

The niche is clear (verified current-state understanding of an unfamiliar repository) and the explicit do-not-use list actively disambiguates from the adjacent skills it could collide with (design, review, implementation, debugging). The proactive conflict resolution pushes it to 5 rather than 4's "minor overlap risk with closely related skills".

5 / 5

Total

17

/

20

Passed

Validation

93%

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

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

relative_links

Relative link issues: 10 missing, 9 deeper-than-1-level

Warning

Total

15

/

16

Passed

Repository

Noorkhalel/saas-ai-skills

Path

skills/codebase-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.