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…
In the article "What I Learned Stealing Ideas from Matt Pocock’s .agents Directory," the author shares their experience of discovering a repository called mattpocock/skills, which contains a collection of markdown files defining instructions and guidelines for an AI assistant to build code without breaking the existing codebase. The author outlines several key takeaways from this repository:
1. The importance of providing context and guardrails to AI agents
2. The inadequacy of generic prompts and the need for explicit guidelines
3. The structure of the repository and how to implement it
The author explains that most people make the mistake of giving AI agents no context about the project's conventions, leading to issues like renaming public APIs, using banned patterns, and writing tests that mock everything. Matt Pocock's approach is different – he treats the AI assistant like a junior engineer who needs a detailed onboarding document, which he achieves by creating a set of markdown files that define explicit rules and guidelines for the AI assistant.
The repository is divided into several categories, including role and tone definitions, explicit "do not" lists, and context injection patterns. One of the most valuable takeaways is the explicit "do not" lists, which prevent agents from introducing unwanted changes or breaking team conventions. The author also highlights the importance of injecting context into the AI assistant's workflow, with specific files designed to be loaded at certain moments based on patterns in the conversation.
The author provides a practical example of how they implemented this structure in their own project, which is a Node.js monorepo with TypeScript and legacy JavaScript. They created a .agents/ directory containing specific skill files for different tasks, such as writing tests and working with the Git workflow. The author shares a testing skill file that includes details on when to use it, the rules to follow, and an example of the desired test format.
This approach has saved the author from many painful experiences when using AI assistants for code assistance.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
