A Claude Code repository analysis Skill should standardize how an agent finds entry points, module relationships, dependencies, tests, and uncertainty. It should not contain a supposedly complete map of the repository. Put the Skill at .claude/skills/repository-analysis/SKILL.md, commit it with the project, give it a specific description, and test its evidence contract against a fixture repository before using it for consequential change planning.
The useful unit is one bounded workflow: receive a target and revision, collect source-backed relationships, label unsupported edges, map tests and risk, then return a predictable report for human review.
Before Building the Skill
A Claude Code repository analysis Skill needs a bounded owner and evidence contract. “Understand the repository” is too broad. A better contract is: “Given a symbol, module, endpoint, or change proposal, identify its entry points, direct relationships, relevant tests, and unresolved risks within a stated scope.”
A codebase Skill should own the repeatable procedure, not a mutable snapshot of repository relationships. That separation keeps the workflow reviewable as the code changes.
Write down the inputs before writing SKILL.md:
- target symbol, behavior, or directory;
- repository revision and working directory;
- excluded paths such as vendored or generated output;
- supported languages and available code-intelligence tools;
- required output fields and verification checks;
- escalation conditions for dynamic or inaccessible evidence.
Keep responsibilities separate. CLAUDE.md is appropriate for stable repository conventions and build commands. A Skill is the on-demand procedure. Current module and dependency relationships must still come from source, code intelligence, tests, or an external knowledge graph for AI coding assistants. For a deeper layer comparison, see Claude Code recipes vs knowledge graph.
Claude Code Skills expose names and descriptions for discovery, then load the full body when used. That makes the description part of the interface: say when the Skill should activate, what target it expects, and what output it produces.
Define the Repository Analysis Workflow
Start the codebase Skill with a small SKILL.md rather than a large reference manual:
---
name: repository-analysis
description: Analyze a specified repository symbol, module, or change surface and return source-backed entry points, relationships, tests, risks, and unknowns. Use for bounded repository analysis before planning a change.
---
1. Confirm the target, revision, and directories in scope.
2. Locate definitions and executable or configured entry points.
3. Trace direct inbound and outbound relationships.
4. Inspect indirect registration and generated boundaries separately.
5. Map specific tests to claimed behaviors.
6. Return evidence tables, unknowns, and verification steps.
This is deliberately procedural. Do not encode facts such as “service A always calls service B” in the Skill body unless they are stable architectural rules with an owner. Ask the Skill to rediscover mutable relations from evidence.
This Claude Code repository analysis Skill example therefore freezes the output contract while leaving current facts to source-backed retrieval.
Freeze an output schema so results can be compared across runs:
| Field | Required content |
|---|---|
| Scope | revision, target, included and excluded paths |
| Entry points | file, symbol, trigger type, evidence |
| Relationships | from, relation, to, direct/inferred/unknown |
| Tests | test name, file, behavior or edge covered |
| Risks | failure mode, affected boundary, proposed check |
| Unknowns | missing tool, dynamic behavior, contradictory evidence |
Require the Skill to stop and ask for scope when the target is ambiguous. A repeatable workflow that begins from the wrong boundary only makes a wrong answer more consistent.
Add Module, Dependency, and Entry-Point Queries
A practical Claude Code repository analysis Skill example should define query classes, not invent commands that may not exist in the reader's environment.
For module discovery, locate package manifests, build targets, module declarations, and top-level imports. Return ownership and responsibility only when supported by source, repository documentation, or an ownership file. Directory names are hints, not architectural proof.
For entry points, inspect executable mains, exported handlers, routes, jobs, event consumers, plugin registration, configuration loaders, and deployment manifests relevant to the target. Ask for the file and symbol that establishes each entry. Treat convention-based framework discovery as an explicit relation, not an ordinary function call.
For dependencies, prefer definitions and references from a configured code-intelligence plugin. Supplement those results with text search for configuration keys, strings, templates, schemas, and generated boundaries. The Skill should distinguish import dependency, call, registration, publication, data read/write, and deployment coupling; collapsing all of them into “depends on” makes later impact analysis unreliable.
For an external graph or search index, define the question and the evidence returned: indexed revision, source location, relation type, and query time. Claude Code can reach external services through MCP, but an MCP connection does not make the graph native or guarantee its correctness.
End every query block with a verification instruction. For example: reopen the defining file, reproduce one reference lookup, and flag any result that points outside the declared revision or scope.
Map Tests and Risk Areas
Make test mapping an evidence task. A test with a matching filename may not execute the path under review, while a contract or integration test in another package may be the strongest check.
Require these fields for each candidate test: test name, file, setup or fixture, entry point exercised, assertion relevant to the target, and coverage status. Use statuses such as directly exercises, covers an adjacent contract, name match only, and not found.
Then classify risk by boundary rather than by generic severity:
- public API or serialized schema compatibility;
- migration and persistent state behavior;
- authorization, tenancy, or secret handling;
- asynchronous delivery, retry, and idempotency;
- generated client or build artifact drift;
- deployment configuration and rollback.
For each material risk, request one existing check and one missing or proposed check. The Skill may recommend a test, but it should not edit code or execute a mutating command during an analysis-only run.
Test the Skill itself on a fixture repository with known entry points, callers, and tests. Include negative cases: aliases, dynamic registration, generated code, an unrelated name match, and one intentionally unknowable edge. The expected output must include “unknown”; otherwise the test rewards confident guessing.
Maintenance and Permission Risks
Assign an owner and review triggers. Update the Skill when its evidence schema, supported tooling, repository layout conventions, or risk policy changes. Do not update it merely to cache a one-off discovery; that belongs in source-backed documentation or a refreshed index.
Permissions need precise wording. The allowed-tools field can pre-approve listed tools while a Skill is active, but Anthropic states that it does not restrict other tools. It is not a read-only sandbox. For an analysis-only workflow, use organization or project permission rules, including deny rules or an appropriate permission mode, and keep workspace trust requirements in mind.
Avoid pre-approving broad shell access simply to make the Skill convenient. Prefer read, search, code-intelligence, and explicitly scoped graph queries. Separate the analysis Skill from any implementation or deployment Skill so a request for impact mapping cannot silently become a mutation workflow.
Operational checks can show whether the Skill loads, not whether its claims are correct. Claude Code's /context view helps inspect loaded configuration, and the skill_activated OpenTelemetry event can indicate invocation in supported monitoring setups. Neither proves that a call edge or test mapping is factual; fixture tests and source review remain necessary.
Version the Skill and its fixtures together. Record the Claude Code version, available code-intelligence plugins, permission mode, fixture commit, and expected evidence schema for every acceptance run. Re-run the suite after changing frontmatter, tool adapters, repository conventions, or a permission rule. Include one denied path and one stale external-index response so the Skill proves it can stop safely, not only complete a happy path. In production sampling, track unsupported relationship claims, missed tests, scope clarifications, and review corrections. A lower file-read count is useful only when these correctness measures remain stable.
Keep a rollback path. If a revised Skill increases false confidence or silently widens its tools, restore the prior reviewed version and preserve the failing output as a regression fixture. Treat Skill maintenance like interface maintenance, not prompt polishing.
FAQ
Who should approve Skill updates?
The repository or platform team can own the shared workflow, but affected module owners should approve changes to scope, evidence requirements, and risk rules. Permission changes deserve a security or tooling-owner review. Use normal code review and require an updated fixture result for behavioral changes.
What should the Skill not automate?
It should not edit code, change permissions, run deployment commands, approve its own evidence, or present inferred relationships as authoritative. Keep implementation, migration, and release operations outside an analysis-only Skill unless the team creates a separately reviewed workflow.
How should teams test Skill output?
Use a versioned fixture repository with known definitions, callers, indirect registrations, tests, and missing edges. Compare structured output, not prose style. Also sample the Skill against real changes and record false relationships, missed tests, unsupported claims, and time-to-evidence.
claude code mcp
MCP is one way Claude Code connects to external tools and data sources. A repository analysis Skill can request a scoped MCP query to a code-search or graph service, then verify returned edges against source. The Skill and the MCP server have separate permissions, ownership, and freshness concerns.
Conclusion
A sound Claude Code repository analysis Skill is a small, reviewable procedure with a strict evidence schema. Keep mutable repository facts outside the Skill, require explicit unknowns, test the workflow against known and negative cases, and enforce read-only behavior through actual permission controls rather than suggestive frontmatter.
Leave a Reply