`mattpocock/skills`: Practical Agent Instructions for Real Engineering Work

The recent surge around mattpocock/skills makes sense: it treats AI agent behavior as a versioned engineering artifact instead of a collection of ad-hoc prompts.

The repository’s core idea is simple. Reusable skills live in an .agents directory, where they can be inspected, copied, reviewed, and adapted to a project. This gives teams a more maintainable way to encode workflows such as debugging, code review, testing, and implementation planning.

The important architectural choice is that skills remain close to the repository rather than hidden inside an external tool configuration. That makes them easier to diff and improve through normal pull requests. It also keeps the instructions portable across agent environments that understand the same directory conventions.

Quick start

Clone the repository and inspect the available files before installing anything:

git clone --depth=1 https://github.com/mattpocock/skills /tmp/mattpocock-skills && find /tmp/mattpocock-skills/.agents -type f | sort

To copy the skills into an existing project:

mkdir -p .agents && rsync -a /tmp/mattpocock-skills/.agents/ .agents/

From there, read the skill files as carefully as you would read source code. Select the instructions that match your workflow, then commit the relevant .agents content alongside the project.

What to watch before production

• Instruction conflicts: Project-level rules, repository conventions, and imported skills may disagree. Define precedence clearly and remove duplicate guidance.
• Context cost: Loading every skill into every task can consume context unnecessarily. Prefer focused, task-specific instructions.
• Reviewability: Treat agent skills as code. Require pull-request review, test important workflows, and avoid instructions that grant broad destructive permissions.

The strongest part of this project is its simplicity. There is no complicated runtime to maintain: just structured, reusable engineering knowledge that can evolve with the codebase. That makes .agents a useful boundary between human process and AI-assisted execution.