improve-codebase-architecture

An agent skill by mattpocock, from mattpocock/skills. Tags: analysis, architecture, codebase, review, visualization.

What it does

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

Install

With the skills CLI, which installs into Claude Code, Codex, Cursor and other agents:

npx skills add mattpocock/skills --skill improve-codebase-architecture

Or copy the skill folder into Claude Code's skills directory by hand (~/.claude/skills for every project, or .claude/skills inside one):

git clone --depth 1 https://github.com/mattpocock/skills
cp -r skills/skills/engineering/improve-codebase-architecture ~/.claude/skills/improve-codebase-architecture

Safety box score

Grade B, low risk: 14 of 100 risk points, rated 2026-10-16. The grade rates what the skill and its scripts can reach on the machine of whoever installs it, across eight categories from shell execution to secrets access. How the score works.

This skill scans a codebase, writes an HTML architecture report to the OS temp directory, and opens it in the browser. The main risks are local process execution to open the report, outbound fetches to Tailwind/Mermaid CDNs, and reliance on remotely hosted rendering code.

Category levels, from 0 (none) to 3 (high)
Category	Level	Why
Code & shell execution	1 (low)	It instructs the agent to run local OS open commands for the generated file (`xdg-open`, `open`, `start`), but it does not ship or eval arbitrary code.
Network access	1 (low)	The report loads Tailwind and Mermaid from CDNs (`https://cdn.tailwindcss.com`, `https://cdn.jsdelivr.net/...mermaid...`), so opening it makes the browser fetch remote resources.
Filesystem reach	1 (low)	It writes a fresh HTML artifact to the temp directory (`<tmpdir>/architecture-review-<timestamp>.html`) and is explicit that nothing should land in the repo.
Secrets & credentials	0 (none)	The skill does not ask for tokens, keys, passwords, `.env` files, browser sessions, or CLI logins.
Privilege & persistence	0 (none)	There is no sudo, global install, service registration, shell startup edit, or OS setting change.
Instruction hijack surface	0 (none)	The skill contains operational instructions and vocabulary constraints, but no prompt injection pattern such as fetched instructions, hidden text, or commands to ignore higher-priority rules.
Irreversible actions	0 (none)	Its effects are limited to local analysis and opening a report; it does not push, deploy, send messages, pay, book, or delete anything.
Transparency	1 (low)	The rendered report depends on remotely hosted, versionless CDN code and Mermaid is initialized with `securityLevel: "loose"`, so the final behavior is partly opaque at runtime.

Before installing

Check that outbound access to `cdn.tailwindcss.com` and `cdn.jsdelivr.net` is acceptable in your environment.
Confirm the agent can write to the OS temp directory and that leaving an HTML artifact there is fine.
If you want fully offline behavior, replace the CDN assets before using the skill.
Run once in a non-sensitive repo first to verify the report-open step behaves correctly on your OS.

Rated 2026-10-16 by an automated review of 3 files from the skill's repository.

Source

Repository: mattpocock/skills (all skills from this repository)
Path: skills/engineering/improve-codebase-architecture/SKILL.md
Branch: main
Updated: 2026-10-05

audit-context-building — Understand a codebase before looking for bugs in it - what each function assumes, what it guarantees, and what it depends on elsewhere.
aws-database — Routes any task involving AWS databases — choosing, comparing, recommending, getting started with.
cavecrew — When to delegate to `cavecrew-investigator` (locate code).
chatting-with-aws-devops-agent — Have a fast, conversational analysis with the AWS DevOps Agent.
diagramming-code — Generates Mermaid diagrams from Trailmark code graphs.
differential-review — Performs security-focused differential review of code changes.