From 26e940d0251cfd265b0d678c79930b590e17f3a7 Mon Sep 17 00:00:00 2001 From: Matteo Rosati Date: Thu, 7 May 2026 11:30:18 +0200 Subject: [PATCH] codebase-analysis skill --- codebase-analysis/SKILL.md | 53 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 codebase-analysis/SKILL.md diff --git a/codebase-analysis/SKILL.md b/codebase-analysis/SKILL.md new file mode 100644 index 0000000..93d4719 --- /dev/null +++ b/codebase-analysis/SKILL.md @@ -0,0 +1,53 @@ +--- +name: codebase-analysis +description: 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.