skills

1. Project Overview

Skills (by Matt Pocock) is an open-source collection of AI agent "skills" — reusable, composable instruction sets that teach coding agents like Claude Code and Codex disciplined, real-world software engineering practices instead of fast-but-unreliable code generation.

2. Background & Positioning

Skills was created to fix four recurring failure modes developers hit when working with AI coding agents:

1. Misalignment between developer intent and agent output — mitigated with structured interview skills such as grill-me and grill-with-docs.
2. Agent verbosity that obscures project clarity — addressed through shared domain language and a CONTEXT.md convention that keeps agents grounded in project terminology.
3. Broken code caused by weak feedback loops — tackled with test-driven development (tdd) and structured debugging (diagnosing-bugs).
4. Architectural decay under rapid, agent-driven development — prevented through design-oriented skills like improve-codebase-architecture.

Unlike large, all-in-one "agent framework" projects, Skills deliberately stays small and unopinionated: each skill is a self-contained, editable Markdown file rather than part of a monolithic system. This makes the collection easy to read, adapt, fork, or trim down to exactly what a team needs, rather than adopting an entire prescriptive workflow.

3. Feature Categories

🛠️ Engineering Skills — User-Invoked (8 skills): explicitly triggered by the developer to orchestrate a workflow.

• ask-matt — router that helps you find the right skill for a task
• grill-with-docs — interview sessions that build a project's domain model
• triage — manage and prioritize issue state
• improve-codebase-architecture — surface and propose architectural improvements
• implement — build features with TDD baked in
  Purpose: give developers explicit entry points for common high-level engineering workflows.

🤖 Engineering Skills — Model-Invoked (8 skills): the agent decides when to apply them during a task.

• tdd — enforces a test-driven development loop
• diagnosing-bugs — structured, hypothesis-driven debugging methodology
• research — investigation workflow that requires cited sources
• domain-modeling — strengthens and maintains consistent project terminology
• code-review — applies dual-axis (correctness + spec-adherence) review standards
  Purpose: bake engineering discipline directly into the agent's default behavior, without the developer needing to ask for it.

📈 Productivity Skills — User-Invoked (4 skills): developer-triggered workflow helpers.

• grill-me — exhaustive planning interviews before large tasks
• handoff — generates conversation summaries for handing work to another agent session
• teach — multi-session skill instruction for onboarding
• writing-great-skills — reference guide for authoring new skills
  Purpose: streamline planning, onboarding, and session-to-session continuity.

🔁 Productivity Skills — Model-Invoked (1 skill): background workflow support.

• grilling — a reusable interview loop consumed by other skills
  Purpose: provide a shared building block that other interview-style skills call into.

4. Key Highlights

• Composable by design — every skill is a small, independent SKILL.md file, so teams can adopt only what they need and edit the rest freely.
• Dual invocation model — skills are split into user-invoked (you ask for them) and model-invoked (the agent applies them automatically), giving fine-grained control over agent behavior.
• Built-in TDD discipline — the tdd and implement skills push agents toward writing tests before code, directly targeting the "broken code from weak feedback loops" failure mode.
• Structured debugging over guesswork — diagnosing-bugs and research require agents to form hypotheses and cite sources instead of freewheeling.
• Domain-language grounding — CONTEXT.md and domain-modeling keep agents using the project's actual terminology rather than generic phrasing.
• Multiple installation paths — works as a managed, auto-updating Claude Code plugin, or as editable files via npx skills for Codex and other agents.

5. Use Cases by Role

• General developers: use grill-me and implement to turn a vague feature request into a well-scoped, test-covered implementation, and handoff to resume work across sessions.
• Project/tech leads: use improve-codebase-architecture and code-review to keep architecture and review standards consistent as agents contribute more code.
• Teams onboarding AI agents into a codebase: use setup-matt-pocock-skills, CONTEXT.md, and domain-modeling to give agents a shared vocabulary and reduce misaligned output from day one.

6. Getting Started

Find what you need — browse the skill catalog and categories in the repository, or ask the router skill inside an agent session:

/ask-matt

Install / integrate:

# Claude Code plugin (managed, auto-updating)
claude plugins install mattpocock-skills
# or inside a Claude Code session:
/plugin install mattpocock-skills

# Codex and other agents (editable local files)
npx skills@latest add mattpocock/skills

# One-time setup per repository
/setup-matt-pocock-skills

Contribute — the skills are intentionally small and easy to adapt; fork the repository, edit or add a SKILL.md, and open a pull request following the guidance in writing-great-skills.

7. Project Structure

skills/
├── .agents/            # Agent configuration files
├── .claude-plugin/      # Claude Code plugin configuration
├── .github/workflows/   # CI workflows
├── docs/                # Documentation
├── scripts/             # Build and utility scripts
├── skills/
│   ├── engineering/     # Code-focused skills (tdd, code-review, etc.)
│   └── productivity/    # General workflow skills (grill-me, handoff, etc.)
├── AGENTS.md            # Agent-facing documentation
├── CLAUDE.md            # Claude-specific setup notes
├── CONTEXT.md           # Project domain model and terminology
└── LICENSE              # MIT license

Each skill lives in its own directory with a dedicated SKILL.md describing when and how it should be used, keeping the collection easy to browse and extend.

8. Related Ecosystem

• Depends on: Claude Code (Anthropic's coding agent CLI) and Codex, the two primary agent runtimes the skills are designed for; the skills npm package/CLI (npx skills) used for installation and updates.
• Complementary tools: any Markdown-driven agent that supports custom skill/plugin loading can, in principle, consume these skill files, since each SKILL.md is a self-contained instruction set.

9. License

✅ Use, modify, and redistribute the code for personal or commercial projects (permitted under the MIT license).
✅ Fork the repository and adapt individual skills to fit your own team's workflow.
❌ Do not remove the original copyright and license notice from redistributed copies.
ℹ️ The MIT license provides the software "as is," without warranty — review the LICENSE file in the repository for full terms before production use.

10. FAQ

Q: Do I need Claude Code to use these skills?
A: No — Claude Code users can install via the plugin marketplace, while Codex and other agent users can install editable files with npx skills@latest add mattpocock/skills.

Q: How do I keep skills up to date?
A: The Claude Code plugin auto-updates; for manually installed files, run npx skills update.

Q: What's the difference between user-invoked and model-invoked skills?
A: User-invoked skills are explicitly triggered by you (e.g. /grill-me), while model-invoked skills (e.g. tdd, diagnosing-bugs) are applied automatically by the agent when relevant.

Q: Can I write my own skill?
A: Yes — see the writing-great-skills skill in the repository for authoring guidance and conventions.

Q: Is there a required setup step after installing?
A: Yes — run /setup-matt-pocock-skills once per repository to configure issue tracking, triage labels, and documentation location.

11. Quick Links

• Repository: https://github.com/mattpocock/skills
• License: https://github.com/mattpocock/skills/blob/main/LICENSE
• Issues: https://github.com/mattpocock/skills/issues
• Discussions/Community: via the repository's Issues and Pull Requests

12. Summary

Skills gives teams a lightweight, editable toolkit for making AI coding agents behave more like disciplined engineers — planning before coding, testing before shipping, and staying grounded in a project's real domain language. It's best suited for developers and tech leads who already rely on Claude Code or Codex and want more consistent, review-ready output without adopting a heavyweight framework.