agentsclimarketplace

Reverse engineer

Skill arjunprabhulal/reverse-engineer-skills/skills/reverse-engineer

Reverse-engineers an unfamiliar codebase by reading it exhaustively and emitting a documentation set — architecture, component, sequence and data-flow Mermaid diagrams, a versioned tech-stack inventory, dependency vulnerabilities, bugs and design issues, performance bottlenecks, a severity-ranked code review, and a prioritized upgrade and optimization plan. Use this whenever the user points at a repo or directory and asks to understand, document, audit, map, review, diagram, or onboard onto code they didn't write — including phrasings like "what does this repo do", "document this codebase", "draw me the architecture", "find the bottlenecks", "is this stack outdated", "review this whole project", "we inherited this service", or "generate mermaid diagrams for this". Also use it for legacy-system takeovers, due-diligence reads, and pre-migration assessments. Prefer this over an ad-hoc skim any time the ask covers more than one file.From its SKILL.md

Install
npx -y skills add arjunprabhulal/reverse-engineer-skills --skill reverse-engineer

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its file declares

Copied from the file, not written here

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

9.6 KB, as published. Nobody here has run it

Reverse Engineer

An unfamiliar repo lies to you in a specific way: the README describes what someone intended two years ago, the directory names describe the original design, and the code describes what actually runs. Documentation produced by skimming names and folder structure reproduces the intention and misses the reality — which is exactly the part the user needed, because the intention is already written down.

So the value here comes from actually reading the code and reporting what it does, including the parts that contradict the docs. Everything downstream — the diagrams, the bottleneck list, the upgrade plan — is only as good as that read.

Every claim in the output traces to a file and line you actually read. No inference from filenames.

Workflow

Run these in order. Each phase feeds the next, and skipping recon makes the read unfocused.

  1. Recon — census the repo, detect the stack, pick a read order → references/recon.md
  2. Read — the line-by-line pass, module by module, taking structured notes → references/code-reading.md
  3. Diagram — architecture, flow, sequence, data model from the notes → references/diagrams.md
  4. Audit — vulnerabilities, issues, bottlenecks, review findings → references/security.md, references/performance.md, references/code-review.md
  5. Recommend — upgrade path and optimization plan, sequenced by payoff → references/upgrade-and-optimize.md
  6. Write — assemble the document set → references/report-template.md

Read each reference file when you reach its phase, not upfront — they're detailed and only relevant in their phase.

Phase 0: Scope honestly, before anything else

Run the census first, because the right strategy depends on size:

python3 <skill-dir>/scripts/repo_census.py <repo-path>

It prints an inventory (languages, LOC, largest files, entrypoints, manifests, test ratio) and a suggested read order. Use its total_significant_loc to choose:

Significant LOCStrategy
< 15kRead every source file end to end. Genuinely line by line.
15k – 100kRead every file in core modules line by line; skim generated code, vendored deps, migrations, and fixtures, and say so.
> 100kFull read of the entry points, core domain, and shared infrastructure; representative sampling elsewhere. State the sampling rule and the coverage percentage in the report.

If subagents are available, fan out one reader per top-level module for anything over ~15k LOC — each returns structured notes in the format from references/code-reading.md, and you synthesize. This is the difference between finishing and running out of context halfway through.

Never silently downgrade coverage. A report that implies a full read when 30% was sampled is worse than one that says "sampled 30%, here's the rule" — the user makes staffing and risk decisions off this. Put the actual coverage in the executive summary.

Phase 1: Recon

references/recon.md covers this in full. The short version: identify entry points (main, index, app, cmd/, Dockerfile CMD, package.json scripts, framework conventions), read every manifest and lockfile for exact versions, read CI config and IaC because they reveal the real deployment topology, and check git log/git blame for hot spots and abandoned areas if the repo has history.

Produce a read order before reading: entry points → routing/dispatch → domain core → persistence → integrations → utilities. Reading in dependency order means each file's callers are already understood.

Phase 2: The read

This is the phase that can't be shortcut, and references/code-reading.md is the one reference to read closely. While reading each file, record: what it does, its public surface, what it calls and what calls it, state and side effects, error handling, and anything surprising — the dead branch, the hardcoded credential, the TODO: fix before launch from 2021, the retry loop with no backoff.

The surprises are the highest-value output. Anyone can regenerate a class diagram; only someone who read line 340 knows the cache is never invalidated on the delete path.

Keep notes in a working file as you go (.reverse-engineer-notes.md in the scratchpad, not in the user's repo) so the synthesis phase has ground truth to cite rather than memory.

Phase 3: Diagrams

Read references/diagrams.md for the diagram set, Mermaid syntax that renders reliably, and the escaping rules that cause most breakage.

Produce at minimum:

  • Architecture — components, external systems, and what talks to what
  • Data flow — how a request or job moves through the system end to end
  • Sequence — the two or three most important flows (auth, primary write path, key integration)
  • Data model — ER diagram if there's a database, class/type diagram otherwise
  • State machine — only if the domain has real states; skip it if forced

A diagram that shows five boxes named after the top-level folders is a table of contents, not an architecture diagram. The test: does it tell a reader something they couldn't get from ls? If not, it's not worth including — go deeper into the actual call graph.

Validate every diagram renders before shipping it. references/diagrams.md has the checklist for the syntax errors that break Mermaid most often.

Phase 4: Audit

Three separate lenses, each with its own reference:

  • Security (references/security.md) — dependency CVEs via real tooling where available, plus code-level classes: injection, authn/authz gaps, secrets in source, unsafe deserialization, SSRF, path traversal, weak crypto. Report exploitability, not just pattern matches.
  • Performance (references/performance.md) — N+1 queries, missing indexes, unbounded results, sync I/O on hot paths, algorithmic complexity, allocation in loops, missing caching, lock contention. Distinguish measured from suspected.
  • Code review (references/code-review.md) — correctness bugs, race conditions, error swallowing, resource leaks, dead code, duplication, test gaps. Severity-ranked with file:line.

Separate confirmed from suspected everywhere. A CVE from npm audit with a reachable call path is confirmed; a pattern that looks like SQL injection but has a parameterized driver underneath is not. Overstating findings costs the user real triage hours and burns the report's credibility on everything else in it.

Phase 5: Recommendations

references/upgrade-and-optimize.md covers this. The core discipline: each recommendation carries effort, risk, and payoff, and the whole set is sequenced so that early items unblock later ones. "Upgrade to the latest version of everything" is not a plan — the plan is which upgrade first, what breaks, and what has to happen before it's safe.

Anchor every version claim to something checked in this session (registry, changelog, EOL date), not to recollection. Version facts go stale, and a confidently wrong "this is EOL" sends someone on a pointless migration.

Output

Write to docs/reverse-engineering/ in the target repo unless the user says otherwise, one file per concern, plus a README.md index. references/report-template.md has the exact structure and section templates.

Tell the user where the files are and lead with the three things that matter most — usually a critical vulnerability, the biggest bottleneck, and the riskiest piece of the upgrade path. The full document set is for later; the summary is what they read now.

Bundled resources

Scripts (run them, don't reimplement):

  • scripts/repo_census.py <path> — inventory, LOC by language, largest files, entrypoints, manifests, test ratio, TODO/FIXME census, suggested read order. Add --json for machine-readable output.
  • scripts/stack_probe.sh <path> — detects manifests and pinned versions, and runs whichever audit tools exist locally (npm audit, pip-audit, govulncheck, cargo audit, osv-scanner, trivy). Skips missing tools cleanly rather than failing.

References (read at the matching phase):

  • references/recon.md — stack detection, version extraction, entry-point discovery, read ordering
  • references/code-reading.md — the per-file note schema and what to look for while reading
  • references/diagrams.md — Mermaid patterns for each diagram type plus syntax that survives rendering
  • references/security.md — dependency and code-level vulnerability audit
  • references/performance.md — bottleneck taxonomy by layer
  • references/code-review.md — review rubric and severity scale
  • references/upgrade-and-optimize.md — sequencing upgrades and optimizations by payoff
  • references/report-template.md — the exact output document set

Keep looking

Skills are one crate of 608,475. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.