Codebase Recon
Understand a codebase before reading any code — git history reveals hotspots, risk areas, team structure, and development momentum.
All commands are read-only git queries; a report file is written only after explicit user confirmation and never committed — least privilege, transparent data flow, no external effects. Deducted for: unverified publisher identity, no stated isolation/rollback provisions, so full marks are unreachable.
The 7 commands are standard git usage with scale-adaptive parameters and internally consistent logic. Deducted for: static review cannot execute anything (cap 10), failure feedback on abnormal inputs (empty repo, shallow clone, non-git directory) is undefined, no tests.
Trigger scenarios are clear (entering an unfamiliar codebase, onboarding), compatibility is declared, requires only git with no unreachable overseas services. Deducted for: undeclared non-fit boundaries (shallow clones, repos without history) and no mention of Chinese-language support.
Well-layered docs (probe → parallel analysis → cross-referencing → report template), version number, MIT license, explicit attribution to the source article. Deducted for: no changelog, no stated maintenance/update path, no known-limitations or FAQ section.
Output is a structured report with a complete template, directly usable and higher value than manually typing the commands. Deducted for: static review cannot verify actual output quality; cross-referencing heuristics and trend thresholds are unvalidated, so score stays below the 7 cap.
Key methodology is traceable to an auditable primary source (the original blog post and its author). Deducted for: no test suite, no CI, no third-party execution evidence; most efficacy claims rest on author statements, below the static cap of 5.
- This is a static source-only review; nothing was executed and confidence is low.
- The skill writes a file only after confirmation and never commits, but review the report path in sensitive repos.
- On shallow clones or repos without history, some outputs (since-window, bus factor) may be misleading; ensure full history first.
- Trend and risk thresholds (20%, 30%, 50%) are author-chosen heuristics, independently unvalidated.
- No Chinese-language support declared; npx/skills.sh and plugin marketplaces reachability from mainland China is unverified.
What does this skill do, and when should you use it?
Codebase Recon is a coding agent skill that analyzes git commit history to give developers a picture of an unfamiliar codebase before reading any code. It first probes repo scale to auto-calibrate analysis windows, then runs 7 git command groups in parallel across dimensions: code hotspots, bug magnets, bus factor, team momentum, firefighting frequency, recently added files, and active contributors. The report cross-references hotspots with bug magnets to flag high-risk files and their primary owners, ending with actionable recommendations on where to start reading and who to talk to. It works in any terminal-based coding agent supporting the Agent Skills Specification and requires only git.
The skill runs in three phases. Phase 1 (Probe) collects repo vitals with one shell command — total commits, first/latest commit dates, branch count — classifying the repo as small (<500 commits), medium (500–10k), or large (>10k) to set the analysis window. Phase 2 runs 7 independent git command groups in parallel: most-changed files (git log --name-only counting), contributor ranking (git shortlog -sn), bug-fix-associated files (grep fix/bug/broken), monthly commit frequency, revert/hotfix emergency commits, newly added files, and active contributors in the last 3 months. Phase 3 cross-references: files appearing in both hotspot and bug-magnet lists are flagged high-risk, with git shortlog -sn -- <file> identifying each file's primary owner; active contributors under 30% of total triggers a bus-factor warning; momentum trend (rising/stable/declining/erratic) is judged by comparing last-3-month averages against the prior 3 months. The final report follows a fixed terminal template and can be saved as a markdown file (never auto-committed).
- A new engineer on day one receives an unfamiliar repo and wants to know which files matter most and who knows them before diving into code.
- A tech lead inheriting a legacy system needs a quick read on knowledge concentration (bus factor) and the active-contributor ratio.
- A consultant or agency evaluating a prospective client project wants to know if development is accelerating or stalling, and how often emergencies happen.
- An open-source maintainer checking whether a module is persistently both hot and bug-prone and should be prioritized for refactoring.
- A team doing quarterly planning wants month-by-month commit trend data to judge whether a project has entered maintenance mode.
What are this skill's strengths and limitations?
- Only requires git — no extra tooling or network access, runs on any git repository out of the box
- Auto-scales time windows and result counts to repo size, so it works for both tiny repos and 10k+ commit monorepos
- Goes beyond raw data: cross-references hotspots with bug magnets, computes active-contributor ratios, classifies momentum trends, and ends with concrete recommendations
- Implemented entirely as prompts plus standard git commands — the logic is fully transparent and auditable
- MIT licensed, with clear attribution to the inspiration article and an explanation of what was extended
- Report quality depends on the host agent's ability to execute shell commands; environments without shell access cannot run it
- Analysis is based purely on commit metadata (messages, filenames, authors) — it never reads code, so it cannot assess code quality or complexity
- Bug-magnet detection relies on git grep keywords (fix|bug|broken), so repos with inconsistent commit messages will undercount bugs
- No test suite, benchmarks, or independent user feedback are provided in the source material
- Firefighting detection likewise depends on commit messages containing revert/hotfix/emergency/rollback
How do you install this skill?
Three installation paths (all from the README): 1) Via skills.sh (works with 20+ coding agents): run npx skills add yujiachen-y/codebase-recon-skill; 2) Via the Claude Code plugin system: run /plugin marketplace add yujiachen-y/codebase-recon-skill, then install the plugin from the marketplace browser via /plugin; 3) Via the Codex plugin system: run codex plugin marketplace add yujiachen-y/codebase-recon-skill, then run /plugins in Codex, choose the Codebase Recon marketplace, and install codebase-recon. The skill file lives at skills/codebase-recon/SKILL.md in the repository.
How do you use this skill?
In your coding agent, invoke /codebase-recon. The skill will: 1) probe the repo to determine its scale (small/medium/large); 2) analyze 7 dimensions in parallel; 3) cross-reference hotspots with bug magnets to identify high-risk files; 4) report findings with actionable recommendations. Requirements are simply a terminal with git and a git repository containing commit history as the working directory. After the report, you can ask to save it as a markdown file.