mattpocock/skills: Agent Skills for Real Engineers

With over 177,000 stars, it provides a standardized set of "runbooks" that turn general-purpose models into specialized collaborators. By moving away from haphazard "vibe coding," you make your agent follow systematic processes for design, testing, and implementation.

Treat these skills as the automated equivalent of a senior developer's onboarding runbook. Rather than building fragmented, custom agents for every task, you use this collection — assembled by Matt Pocock straight from his own .agents directory — to package procedural knowledge into composable resources. These skills are plain Markdown files that define exactly how an agent should behave during the critical phases of the software development lifecycle (SDLC).

Agents fail most often when they lack context or misunderstand the brief. This project targets those failure modes with small, readable units that prioritize engineering fundamentals — rituals like Test-Driven Development (TDD) and Domain-Driven Design (DDD) that reduce software entropy. It turns the agent from an overconfident junior into a methodical collaborator.

What is mattpocock/skills?

A "skill" in this architecture is a directory containing a SKILL.md file with YAML frontmatter. That metadata — the skill's name and description — is the first level of progressive disclosure. At startup, the agent pre-loads only this metadata into its system prompt, so it can discover when a skill is relevant without spending context on instructions it doesn't yet need.

When the agent decides a task needs a specific skill, it moves to level two by reading the full body of the SKILL.md file. For more complex operations, level three lets the agent navigate additional linked resources or scripts bundled in the skill directory. This tiered loading keeps the context window lean, which is critical for preserving reasoning accuracy and token efficiency across long sessions.

Beyond prose instructions, skills let agents execute deterministic code — Python or Bash scripts — as tools. Large language models reason well but are unreliable at tasks that demand precision, like complex sorting or data extraction. By bundling scripts inside a skill, you give the agent a way to perform those operations with a consistency that token generation alone can't match.

This design follows an anti-framework philosophy. Instead of an opaque process that is hard to debug, you get transparent, editable Markdown you can read, fork, or rewrite in a minute or two. That composability keeps the agent's behavior predictable and lets you tailor the instructions to your team's architectural requirements.

Why "skills for real engineers"?

The project is a direct response to four common failure modes in agentic development: misalignment, verbosity, execution errors, and architectural decay (the "ball of mud"). These failures show up when developers lean on "vibe coding" — a reactive style where you hope a vague prompt returns a good result. To counter it, the repo draws heavily on "Pragmatic Programmer" and "Extreme Programming" influences (Dave Thomas, Andy Hunt, and Kent Beck) to prioritize risk mitigation.

Alignment is handled through "grilling" sessions that force the agent to ask detailed questions before it touches the code. This heads off the "agent built the wrong thing" error by making you and the agent reach a shared understanding first. To solve verbosity, the project advocates a "ubiquitous language" stored in a CONTEXT.md file. Teaching the agent your domain terms lets it use concise language instead of reinventing jargon, which reduces context rot and lowers token usage.

Engineering fundamentals like TDD and DDD are encoded into the agent's daily habits. The repository enforces a red-green-refactor loop where the agent is prohibited from skipping the failing-test phase, so the code it produces is validated by a tight feedback loop. By caring about the design of the system every day, these skills help you rescue codebases from the entropy that agents tend to accelerate.

The anti-framework stance is the key differentiator. Monolithic systems like GSD or Spec-Kit often own the entire development process, which makes bugs inside the workflow itself hard to resolve. These skills are small, composable units instead. If a TDD ritual is too strict for your project, you edit the Markdown or delete the file — keeping the agent's instructions focused on the work at hand.

The main flow and the skills worth using

The recommended lifecycle follows a rigorous progression: grilling → spec → tickets → implement → code review. You begin with /grill-me (or /wayfinder for larger efforts) to establish alignment. Once the requirements are pinned down, the agent uses /to-spec to synthesize the conversation into a technical specification, which is then broken into concrete units through /to-tickets.

A few high-value skills define this journey. /wayfinder is designed to resolve "session anxiety" and foggy ideas by breaking massive tasks into scoped "decision tickets." For implementation, /code-review is indispensable: it explicitly invokes Martin Fowler's refactoring smells — "mysterious name," "feature envy," "data clumps," "primitive obsession," "divergent change," "speculative generality," "message chains," and "middleman" — to trigger the agent's own prior knowledge of architectural rot.

There is a strict distinction between user-invoked and model-invoked skills. User-invoked skills are orchestrators — like /grill-me or /triage — that you explicitly call to start a process. Model-invoked skills are subroutines — like /tdd or /diagnosing-bugs — that the agent reaches for automatically when the task fits. A firm rule holds the system together: a user-invoked skill can call model-invoked ones, but it can never call another user-invoked skill.

The /implement skill is the bridge to production. It directs the agent to work through the spec or tickets while driving the /tdd loop at pre-agreed seams. By finishing with a code review that checks the diff against both repo standards and the originating spec, the system ensures every contribution is both requirements-aligned and technically sound.

Installing and setting it up in your repo

There are two philosophies for integration. The skills.sh installer (run through npx) is for engineers who want to hack on and own the files — it copies editable skills into your .claude/skills/ directory. The managed Claude Code plugin is for those who want a read-only, always-current bundle they subscribe to rather than fork. If you need to standardize skills across teams, community forks are available for bulk installation.

The mandatory first step is running /setup-matt-pocock-skills. This matters because it moves the agent from a generic state to a repo-aware one. During setup you define your issue tracker (GitHub, Linear, or local), set your triage labels, and establish the paths where the agent should save documentation. This happens once per repository and sets the ground rules for every later session.

npx skills add mattpocock/skills

Once installed, avoid the "junk drawer" effect by installing only the skills you actually need; a lean, curated set beats a bloated one. Loading irrelevant procedures or conflicting instructions can cause reasoning errors, so keep the instruction set tight. By explicitly linking the agent to your real issue tracker and triage workflow, you turn the AI into a teammate that understands your local conventions.

This setup makes the agent a participant in your existing infrastructure, not just a text generator. When it knows exactly where specs go and how tickets are structured, it can automate the more complex parts of the lifecycle without manual hand-holding — the transition from isolated prompts to a continuous engineering process.

What changed in v1.1?

Version 1.1 introduced naming shifts to align with professional practice. /to-prd was renamed to /to-spec because most agent-generated documents are technical specifications, not high-level product documents; "spec" is now the unified through-line term across the suite. Similarly, the planning and issue skills were merged into /to-tickets, moving away from tracker-specific jargon toward the more general idea of "tickets" as the journey toward a destination.

The headline addition is /wayfinder. It manages "session anxiety" for massive tasks that won't fit in one agent session, breaking a foggy idea into a shared map of decision tickets on your issue tracker so you can resolve them one at a time. That keeps the destination clear before any significant implementation begins, preventing the agent from blowing out of its smart zone.

/tdd became reference-only material to better support autonomous "AFK" (away-from-keyboard) agents. In earlier versions, the agent would pause to ask you to confirm every test step; making the skill reference-only lets it follow the red-green-refactor loop independently, which speeds up autonomous work. Refactoring also moved out of the TDD loop entirely and into the code review phase, keeping the implementation session focused.

The update sharpened code review too. Sub-agents now explicitly reference more than ten distinct Fowler code smells. Invoking those specific terms triggers the agent's deep training on refactoring, letting it flag issues like "feature envy" or "speculative generality" that it might otherwise ignore. It makes the review process far more effective at catching architectural regression.

Limitations and the costs you take on

Despite the universal nature of the engineering rituals, the repository leans heavily toward the TypeScript and Node.js ecosystems. Many skills assume you use specific tools like Husky, Vitest, and Prettier. If you work in a different stack — Django, Go, or Rust — several tooling-specific skills will need significant forking and manual adaptation to be useful.

There is a non-trivial maintenance burden. To prevent accuracy regression, the human engineer must actively maintain the CONTEXT.md (shared language) and the Architecture Decision Records (ADRs). If those files rot, the agent quickly returns to generic terminology and poor architectural decisions. This context rot is the primary risk: the skills provide the structure, but the human still owns the knowledge management.

These complex skills also rely on high-tier frontier models. Demanding routines — the relentless interrogation in /grill-me or the architectural scan in /improve-codebase-architecture — often fail on smaller or less capable models, which may bail out of grilling sessions early or fail to follow the deterministic steps a proper TDD loop requires, leading to unreliable output.

Finally, avoid ritual for ritual's sake. Installing the entire repository without understanding the underlying discipline just gives you an unorganized junk drawer of instructions. If a skill adds ceremony without improving the output or the clarity of the plan, delete it. The goal is to reduce software entropy, not to create paperwork for your agent.

Where should you start?

On day one, target the most common failure mode: agent overconfidence. Adopt /grill-me immediately and use it before every change. It forces the agent to stop and interrogate you, narrowing the communication gap. Install /git-guardrails-claude-code as a safety measure too, so the agent can't perform destructive git operations without explicit human approval.

Next, establish your project's shared language. Create a CONTEXT.md file to document your domain terminology. By defining one word where the agent would otherwise use twenty, you cut token usage and keep variable names and module boundaries consistent with your domain model. This ubiquitous-language move pays off in every later session by improving the agent's reasoning speed and accuracy.

Adopting skills incrementally beats a bulk install. A skill should earn its place by solving a tangible problem. Start with the planning and grilling skills, then move to /tdd once you're comfortable with how the agent handles your test suite. This "allowed-to-stay" approach keeps the agent's instruction set lean and relevant to your workflow.

Ultimately, focus on getting /setup-matt-pocock-skills right. Linking the agent to a real issue tracker and defining your triage labels turns it into a repo-aware teammate rather than a simple chatbot. Once it understands your conventions and where the documentation lives, you can start automating the more complex parts of the SDLC with confidence.

When is it worth adopting?

The mattpocock/skills repository is a high-leverage tool for lead engineers who want to move beyond the unpredictability of vibe coding. For serious projects that need long-term maintainability and a clear architecture, the setup time is a worthwhile investment — it transforms the agent from a text generator into an opinionated teammate that respects the fundamentals of software design and testing.

There are no magic prompts here. The real value is bringing classic software principles into your daily interaction with AI. Instead of waiting for the agent to become disciplined on its own, you impose that discipline through well-structured skills — the path to shipping not just faster, but with a steadier hand.

References

• mattpocock/skills — Skills for Real Engineers (GitHub)
• skills v1.1 changelog: /wayfinder, /to-spec, /to-tickets — Matt Pocock (aihero.dev)
• Equipping agents for the real world with Agent Skills — Anthropic
• skills.sh: npm for Agent Skills — DEV Community
• How to Use Matt Pocock's Skills for Claude Code: A Complete Guide — Tosea.ai
• Matt Pocock's Skills Review for Claude Code — andrew.ooo
• Matt Pocock's Skills Repo Is a Better Pattern Than Vibe Coding — Developers Digest
• New Skills! v1.1 brings /wayfinder, /research, /implement — Matt Pocock (video)