Skills/codebase-analysis/SKILL.md

name, description

name	description
codebase-analysis	Analyze a codebase to understand architecture, dependencies, runnable tasks and runtime information.

Codebase Analysis Skill

Use this skill when asked to inspect, explain, refactor, extend, debug, or assess an unfamiliar codebase.

Goals

• Build a concise mental model of the codebase.
• Identify entry points, core modules, data flow, and external dependencies.
• Identify all existing runnable scripts (ex: run the dev server, run in production, etc.)
• Surface risks, conventions, and likely impact areas.
• Produce actionable findings before proposing code changes.

Process

1. Inspect the codebase structure.
2. Read top-level docs: README, AGENTS, architecture notes, contributing docs, and setup files.
3. Identify languages, frameworks, package managers, build tools, test and run commands.
4. Locate application entry points and configuration files.
5. Trace the relevant feature path from input to output.
6. Check tests, fixtures, CI workflows, and lint/type settings.
7. Summarize findings with file references and uncertainty.

Heuristics

• Prefer reading existing conventions over inventing new patterns.
• Do not assume framework behavior when config or code contradicts defaults.
• Treat generated, vendored, minified, and lock files as supporting evidence only.
• Search for similar implementations before designing a new one.
• Verify public APIs, side effects, and persistence boundaries before editing.

Output Format

Provide:

• Overview: what the codebase does.
• Architecture: main components and how they interact.
• Relevant files: files inspected and why they matter.
• Execution path: request/event/job flow, if applicable.
• Dependencies: important internal and external dependencies.
• Risks: fragile areas, missing tests, unclear behavior.
• Next steps: recommended investigation or implementation plan.

Guardrails

• Do not make broad claims without file evidence.
• Mark guesses explicitly as assumptions.
• Do not edit code until the impact area is understood.
• Keep the summary concise and focused on the user’s task.