# 5 mattpocock/skills Help You Understand Your App [2026]

> You shipped an app with AI and can't explain how it works. Here are the exact mattpocock/skills to install first to finally understand your own codebase.

- Canonical: https://www.kunalganglani.com/blog/mattpocock-skills-understand-vibecoded-app
- Author: Kunal Ganglani
- Published: 2026-10-12 · Updated: 2026-10-12
- Category: Technology · Tags: claude-code, ai-coding, developer-tools, vibe-coding, developer-productivity

## TL;DR

You used an AI tool to build an app, it works, and now someone asks how it works and you freeze. That's the vibecoding gap, and it's measurable: AI agents write far more code than humans can review. Matt Pocock's open-source skills repo gives your AI assistant small, focused commands to explain your own codebase back to you. Point improve-codebase-architecture at your repo to map how it's built, diagnosing-bugs to trace why something breaks, and wayfinder or research to understand unfamiliar code. It works with Claude Code, Cursor, Codex, and Copilot. This walks through which skills to install first and what they actually tell you.

mattpocock/skills is an open-source collection of 55 composable agent skills that plug into [Claude Code](/blog/github-copilot-vs-claude-code), Cursor, Codex, and Copilot, letting your AI assistant explain and map existing code instead of only generating more of it. Created by Matt Pocock in February 2026, the repo has crossed 287,856 GitHub stars and 27.6 million installs in roughly eight months.

That speed isn't an accident. The collection solves the question haunting a whole generation of vibecoders: how do you understand the app you shipped but still can't explain? You prompted your way to a working product. It runs. Then someone asks how authentication works, or why the build broke, and you freeze. This post maps the specific skills that close that gap.

## What Is mattpocock/skills (and Why Matt Pocock Built It)

[mattpocock/skills](https://github.com/mattpocock/skills) is a repository of "agent skills" — small, single-purpose instruction files your AI coding assistant loads on demand to perform one engineering task well. Each skill behaves like a named command: `/improve-codebase-architecture`, `/diagnosing-bugs`, `/research`. As of October 12, 2026 the repo carries 287,856 stars and 24,159 forks, shipped its v1.3.1 release on October 4, and crossed 27.6 million installs on the skills.sh marketplace. All of it since February 2026.

![black flat screen computer monitor](https://cdn.sanity.io/images/vzekdneq/production/a49b797ab205ab8fa9a462f799facde2ba9b30e9-1200x675.webp)

[Matt Pocock](https://www.aihero.dev/skills), the TypeScript educator behind Total TypeScript and AI Hero, was deliberate about what this is. His README is blunt: these are "my agent skills that I use every day to do real engineering — not vibe coding." He built them as an alternative to process-owning frameworks like GSD, BMAD, and Spec-Kit, which he argues "take away your control and make bugs in the process hard to resolve." Every skill is small, composable, and model-agnostic by design.

> Vibe coding gets you a running app. It does not get you the ability to explain why it runs. That gap is the whole problem.

The distinction is subtle but total. A skill teaches your agent *how to think* about one task, so the output is your assistant explaining your code back to you in structured form, not emitting another pile of it.

## The Vibecoding Gap: Why You Can't Explain Your Own App

"Vibe coding" was coined by [Andrej Karpathy](https://en.wikipedia.org/wiki/Vibe_coding) in February 2025, describing a flow where you lean fully into the model, accept the diffs, and barely read the code. Merriam-Webster flagged it as trending slang a month later, and Collins named it Word of the Year for 2025. The practice went mainstream far faster than the skills to clean up after it did.

![Lines of colorful JavaScript code displayed on a dark screen](https://cdn.sanity.io/images/vzekdneq/production/c955d26de8fdb0429f885023f8c4ab5de0a88174-1200x675.webp)

Here is the thing nobody building with these tools wants to hear: shipping an app is not the same as understanding it. When you can't explain your own codebase, every bug is a mystery, every security review is a guess, and every new feature risks breaking something you didn't know existed. That's not a character flaw. It's a structural consequence of how [vibe coding](/blog/vibe-coding-best-practices-2026) works. The comprehension step gets skipped because the app already runs.

I've felt a version of this running this blog's own 7-agent publishing pipeline across 261+ posts. The lesson that keeps repeating: composition beats monoliths, and understanding beats volume. An agent that emits a mountain of code you can't trace is a liability, not an asset. The skills that help are the ones that force structure onto what already exists.

## The 5 Skills That Help You Understand Your App

If you shipped something with AI and want to understand it, install these first. This is the subset of the repo aimed at comprehension, not building:

![JavaScript code displayed on a dark screen with colorful syntax highlighting](https://cdn.sanity.io/images/vzekdneq/production/1b98f11a4dc52f48e669aa24dbd26367ad92d7a2-1200x675.webp)

1. **improve-codebase-architecture** — maps how your app is actually structured, names the layers and boundaries, and flags where the design fights itself. At 1.1 million installs, it's the flagship "understand your app" skill.
1. **diagnosing-bugs** — traces *why* something breaks instead of papering over it, walking the call path from symptom to root cause (767.9K installs).
1. **research** — investigates an unfamiliar part of your codebase or a dependency before you touch anything (650.5K installs).
1. **wayfinder** — orients you inside an unknown area of the repo. It answers "where does X live and what talks to it?" (655.9K installs).
1. **ask-matt** — surfaces Pocock's own engineering opinions when you need a second brain on a decision.
Notice what's missing. `grill-me` (1.3M installs) and `tdd` (1.1M installs) are build-and-ship skills. They're excellent, but they assume you already know what you're doing. For comprehension, start with architecture, bugs, and orientation.

## How the Skills Are Organized: Setup, Main Flow, Shaping, Engineering

The repo groups its 27 core skills into four stages. **Getting Started** sets up the toolchain. The **Main Flow** runs a real feature end to end: `grill-with-docs` → `to-spec` → `to-tickets` → `implement` → `code-review` → `retro`. **Shaping** covers early thinking: `wayfinder`, `prototype`, `research`. **Engineering** is where the comprehension skills live: `improve-codebase-architecture`, `diagnosing-bugs`, `triage`.

If you're a vibecoder, ignore the Main Flow at first. Your app already exists, so you don't need the spec-to-ticket pipeline yet. Start in Shaping and Engineering. Those map cleanly onto the only question you care about right now: *why does my app work this way?*

## How to Install mattpocock/skills (Claude Code, Cursor, Codex, Copilot)

The skills are distributed through the skills.sh marketplace and work with [Claude Code](/blog/github-copilot-vs-claude-code), Cursor, Codex, and GitHub Copilot. Run the `setup-matt-pocock-skills` skill (988.3K installs) once to wire the collection into your agent, then invoke individual skills by name inside a session.

From a terminal in your project directory, point your agent at the skill marketplace and install the ones you want. Each skill lands as a markdown instruction file your assistant reads when you call it. No build step, no config server, no lock-in. Delete the files and the behavior is gone. That portability is the point.

One clarification on terminology, because people conflate them. A *skill* is an instruction set that shapes how the model reasons about a task. A *plugin* adds a capability or integration, a new tool the agent can call. Skills change the thinking; plugins change the toolbox. mattpocock/skills sits firmly in the first camp, which is exactly why it works across four different assistants without rewriting anything.

## Walkthrough: Running /improve-codebase-architecture on a Vibecoded Repo

Here's what actually happens when you point `/improve-codebase-architecture` at an app you don't understand. The skill doesn't start editing. It starts *reading*. It walks your directory tree, identifies entry points, and reconstructs the architecture as it finds it, not as you imagine it.

The output is a written map. You get a summary of the major layers (say, a Next.js frontend, a thin API route layer, a database client, and a tangle of utility files), an honest assessment of where responsibilities leak across boundaries, and a prioritized list of the structural problems that will bite you later. For a typical Lovable or Bolt export, that usually means duplicated data-fetching logic, business rules buried in UI components, and no clear seam between your app and the services it calls.

The value isn't the refactor it proposes. It's that you can finally *read* your own app in plain English. Pair it with `diagnosing-bugs` when something breaks and `wayfinder` when you're lost, and you've turned an opaque blob into something you can reason about. If the architecture report scares you, that's your signal to run a proper [vibe coding tech debt audit](/blog/vibe-coding-tech-debt-audit) before you add another feature.

Here's Pocock explaining the small-skill philosophy that makes this composability work:

[Watch: /handoff is my new favourite skill](https://www.youtube.com/watch?v=dtAJ2dOd3ko)

## Why This Matters Now: The AI Code Review Bottleneck

The "I don't understand my app" problem is worth taking seriously right now because it's finally measured. A Harvard University study by [Fiona Chen and James Stratton](https://arstechnica.com/ai/2026/10/ai-coding-agents-generate-more-code-but-not-more-software/), published October 9, 2026, analyzed Jellyfish analytics covering 300 million work events across 700+ software firms through March 2026. Their finding: AI coding agents increase code *volume* but not shipped software output.

Why? Human review is the bottleneck. The study found "the code review process significantly increases in length, pull requests are more likely to require revisions, and reviewers leave more comments." More code, more reviews, no more product. That's the industry-scale version of the exact problem a solo vibecoder hits. Generation got cheap. Understanding did not.

This tracks with the single most useful lesson I took from building compliance scaffolding at Rise People: understanding baked in early beats review bolted on at PR time. The same logic applies to your vibecoded app. Running a comprehension skill before you add the next feature is cheaper than discovering in review that nobody, including you, knows how the thing works. Good [AI code review tools](/blog/ai-code-review-tools-2026-compared) help, but they can't substitute for an author who understands the code.

## mattpocock/skills vs GSD, BMAD, and Spec-Kit

The case for Pocock's approach over heavier frameworks comes down to control versus process ownership.

| Dimension | mattpocock/skills | GSD / BMAD / Spec-Kit |
| --- | --- | --- |
| Unit of work | Small, composable skills | Full process / workflow |
| Control | You invoke what you need | Framework owns the flow |
| Tool support | Claude Code, Cursor, Codex, Copilot | Varies, often framework-specific |
| Learning curve | One skill at a time | Adopt the whole method |
| Best for | Solo devs, vibecoders, incremental use | Teams standardizing a pipeline |

Heavy frameworks make sense when a team needs one shared method. For a vibecoder trying to understand an app they already shipped, that's overkill. You don't want to adopt a methodology. You want to answer one question. Pocock's bet is that small skills you can pick up individually beat process frameworks that demand all-or-nothing buy-in. Think of it as a lighter-weight [agent framework](/blog/loop-engineering-agent-loops): you compose behavior from small parts instead of inheriting a whole pipeline. His repo isn't the only [agentic AI](/blog/superpowers-agentic-skills-framework) skills collection chasing this idea, but its 27.6M installs suggest the composable model is winning. For the broader design pattern behind composable agents, the [AI agents](/pillars/ai-agents) pillar goes deeper.

## Getting Started Checklist

- Install `setup-matt-pocock-skills` once to wire the collection into your agent.
- Run `/improve-codebase-architecture` on your repo and read the full report before touching anything.
- Keep `/diagnosing-bugs` on hand for the next thing that breaks. Resist the urge to just re-prompt.
- Use `/wayfinder` and `/research` whenever you're lost in unfamiliar code.
- Only move to the Main Flow (`to-spec`, `implement`, `code-review`) once you understand what you've already got.
Based on this site's own Search Console data, the "vibe coding patterns" topic draws just 91 impressions over 90 days while the adjacent "AI coding assistants" cluster pulls 44,264. People are deep into *using* these tools and only now starting to search for how to *understand* what they built. The repos that win the next year won't be the ones that generate the most code. They'll be the ones that make the humans using them smarter about the code they already have. Install the comprehension skills first, and you stop being a passenger in your own app. For more on choosing tools, compare [free vs paid vibe coding tools](/blog/free-vs-paid-vibe-coding-tools), the trade-offs in [Cursor vs Claude Code](/blog/cursor-vs-claude-code), and the broader workflow patterns in the [Dev Tools & AI Workflow](/pillars/developer-tools-workflow) pillar. If you need to tear an app down to first principles, the [reverse-engineering-with-agents](/blog/rea-reverse-engineer-anything-agents) approach pairs well with Pocock's skills.

Photo by Clint Patterson on Unsplash.

## FAQ

### What is the difference between a Claude Code skill and a plugin?

A skill is an instruction set that shapes how the model reasons about a specific task, like diagnosing a bug or mapping architecture. A plugin typically adds a new capability or integration the agent can call. Skills change the thinking; plugins change the toolbox. mattpocock/skills is a skills collection, which is why it works across Claude Code, Cursor, Codex, and Copilot without being rewritten.

### Which skill should I use to understand my codebase's architecture?

Start with improve-codebase-architecture, the most-installed comprehension skill at 1.1 million installs. It reads your repo, reconstructs the actual structure, names the layers, and flags where the design fights itself. Pair it with wayfinder to navigate unfamiliar areas and diagnosing-bugs when something breaks.

### Is vibe coding safe for production apps?

Not without a comprehension step. Vibe coding is fine for prototypes, but critics flag maintainability gaps and security risks when nobody understands the generated code. Before shipping to production, run an architecture skill and a security pass so you can actually explain and defend how the app works.

### How is mattpocock/skills different from BMAD, GSD, or Spec-Kit?

Those are process-owning frameworks that ask you to adopt a whole workflow. mattpocock/skills is a set of small, composable commands you invoke one at a time, keeping control with you. Matt Pocock built it specifically because the heavier frameworks 'take away your control and make bugs in the process hard to resolve.'

### How do I install mattpocock's skills?

Run the setup-matt-pocock-skills skill once from your project directory to wire the collection into your agent, then call individual skills by name during a session. The skills are distributed through the skills.sh marketplace and land as markdown instruction files, so there is no build step or server to manage.