Skip to content
mcp/skillhub

Agent Skill

Improve Codebase Architecture skill

improve-codebase-architectureMatt Pocock Skillsskills/engineering/improve-codebase-architecture/SKILL.md

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

300kMIT

always on

32 tokname + description

once used

1,304 tokSKILL.md body

bundled files

27 KB

installs

1.2Mskills.sh

Install the Improve Codebase Architecture skill

Skills CLI (Claude Code, Codex, Cursor and others)

npx skills add https://github.com/mattpocock/skills --skill improve-codebase-architecture

Claude Code, by hand (all projects)

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

For one project only, copy the folder into .claude/skills/ in that project instead. It is marked disable-model-invocation, so the agent won't pick it on its own: you run it as /improve-codebase-architecture.

What it costs your context

Agent Skills load in three steps. Tokens counted with the o200k tokenizer; your model's count will differ a little.

WhenWhat loadsCost
Every sessionName and description32 tok
When the agent uses itThe SKILL.md instructions1,304 tok
Only if opened2 bundled files (7 KB)varies

Until it is used, improve-codebase-architecture costs about 43× less than the median MCP server we measured (1,362 tokens on every turn). Installing all 38 skills from mattpocock/skills would load 1,290 tokens of descriptions. Skills vs MCP study

Checks

Our checks found nothing to flag: it follows the Agent Skills specification's naming and size guidelines and doesn't pipe downloads into a shell.

Checked 2026-10-22 · method

What's inside

The headings of its SKILL.md. Read the full file on GitHub.

  • Improve Codebase Architecture
  • Process
  • 1. Explore
  • 2. Present candidates as an HTML report
  • 3. Grilling loop

More skills from mattpocock/skills

All skills in this repo
  1. grill-memattpocock/skills

    A relentless interview to sharpen a plan or design.

    1.4M14 tok idle · 9 in use
  2. grill-with-docsmattpocock/skills

    A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.

    1.2M30 tok idle · 17 in use
  3. tddmattpocock/skills

    Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.

    1.1M33 tok idle · 735 in use
  4. setup-matt-pocock-skillsmattpocock/skills

    Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.

    1.0M44 tok idle · 1,673 in use
  5. handoffmattpocock/skills

    Compact the current conversation into a handoff document for another agent to pick up.

    1.0M19 tok idle · 151 in use
  6. triagemattpocock/skills

    Move issues and external PRs through a state machine of triage roles, categorise, verify, grill if needed, and write agent-ready briefs.

    979k33 tok idle · 1,510 in use
  7. prototypemattpocock/skills

    Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.

    976k39 tok idle · 597 in use
  8. grillingmattpocock/skills

    Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.

    965k37 tok idle · 390 in use