What I Learned Stealing Ideas from Matt Pocock’s `.agents` Directory
What I Learned Stealing Ideas from Matt Pocock’s .agents Directory If you’ve spent more than ten minutes on TypeScript Twitter, you know Matt Pocock. He’s the guy who made zod and TS generics feel approachable. But a few weeks ago, I stumbled onto something more interesting than his type gymnastics: a repo called mattpocock/skills , which is literally a dump of his .agents directory. At first I thought it was a joke. Then I realized it’s a goldmine for anyone building AI-assisted coding workflows. This isn’t a “prompt engineering” fluff piece. This is about how a working engineer structures the instructions, context, and guardrails that an AI agent needs to actually ship code without wrecking your codebase. Here’s what I learned, what I copied, and what I’d change. The Problem: Your AI Agent Is Only as Good as Your Defaults Let me set the scene. You’ve got Cursor, or Claude Code, or some other agentic tool. You ask it to “refactor this function.” It does. Then you realize it: Renamed a public API that three other files depend on. Used a pattern your team explicitly banned six months ago. Wrote tests that mock everything so they pass but assert nothing. Sound familiar? The root cause isn’t the model. It’s that you gave the agent zero context about your project’s conventions. Most people write a two-line system prompt and expect magic. Matt’s approach is different: he treats the agent like a junior engineer who needs a detailed onboarding doc, not a mind reader. His skills repo is essentially a set of Markdown files that define, in explicit terms, how the agent should behave in specific situations. Think of it as a CONTRIBUTING.md for your AI pair programmer. What’s Actually in the Repo (Don’t Just Clone It) I’m not going to paste the whole thing here—go read it yourself (link: github.com/mattpocock/skills ). But structurally, it breaks down into a few key categories that matter. 1. Role and Tone Definitions The first thing you’ll notice is that Matt doesn’t just say