skills

Product Introduction

1. Definition: Skills is a curated, open-source repository of modular, composable prompts (called "skills") designed for AI-powered coding agents like Claude Code, Codex, and other Agent-Skills-standard harnesses. It is a technical toolkit for software engineering workflows.
2. Core Value Proposition: It exists to translate decades of established software engineering fundamentals—such as Test-Driven Development (TDD), Domain-Driven Design (DDD), and deliberate system architecture—into repeatable, AI-executable practices. Its core value is enabling developers to build robust, maintainable applications with AI assistance, moving beyond basic code generation to controlled, high-quality engineering.

Main Features

1. /grill-with-docs: A user-invoked skill that combines a rigorous planning interview with active domain modeling. It works by prompting the AI agent to ask exhaustive questions about a planned change, simultaneously building a shared project glossary. This process directly updates the project's CONTEXT.md (domain language) and creates Architecture Decision Records (ADRs), embedding knowledge into the repository itself.
2. /tdd: A model-invoked skill that enforces a strict red-green-refactor Test-Driven Development loop. It works by guiding the AI to first write a failing test for a specified behavior, then implement the minimal code to pass the test, and finally refactor. This creates a tight feedback loop, ensuring code is correct by construction and aligns with Agile and Extreme Programming (XP) methodologies.
3. /improve-codebase-architecture: A user-invoked skill that performs a static analysis and design review. It works by scanning the codebase to identify "deepening opportunities"—places where modules can be made deeper (more functionality behind a simple interface) according to John Ousterhout's philosophy. It then generates an interactive HTML report and guides the user through refactoring decisions, combating software entropy.
4. /to-tickets & /implement: A workflow pair for project management. /to-tickets decomposes a plan or spec into discrete, traceable work items (tickets), defining blocking dependencies. /implement is the execution skill that consumes these tickets, driving the /tdd skill at agreed-upon seams and concluding with a structured /code-review before committing changes, enabling predictable, incremental delivery.
5. /diagnosing-bugs: A model-invoked skill that formalizes the debugging process. It works by enforcing a disciplined diagnostic loop: reproduce the issue, minimize the failing case, form a hypothesis, instrument the code to gather data, apply a fix, and finally create a regression test. This systematic approach replaces ad-hoc debugging with a reliable engineering protocol.

Problems Solved

1. Pain Point: AI Misalignment and Vague Requirements. Coding agents often produce incorrect or undesired output due to ambiguous instructions, leading to wasted time and rework.
2. Target Audience: Professional Software Engineers and Engineering Teams using AI coding assistants; Tech Leads and Architects who need to maintain code quality and system design in AI-augmented workflows; Solo Developers and Startup Teams building production applications with limited resources.
3. Use Cases: Scaffolding a New Feature: Using /grill-with-docs to define scope and domain language, then /to-tickets and /implement to build it. Refactoring Legacy Code: Using /improve-codebase-architecture to identify and systematically improve problematic modules. Squashing a Heisenbug: Invoking /diagnosing-bugs to guide the AI through a structured, evidence-based debugging session. Onboarding to a Codebase: Using the generated CONTEXT.md and ADRs as living documentation for both human and AI contributors.

Unique Advantages

1. Differentiation: Unlike monolithic AI "agent frameworks" (e.g., GSD, SMOL) that control the entire process, Skills is modular and non-opinionated about the overall workflow. It provides specific, composable tools that integrate into any process. Compared to one-off prompts, it offers a cohesive, principled system based on proven engineering literature.
2. Key Innovation: The deep integration of Domain-Driven Design (DDD) principles into the AI development loop. The /grill-with-docs skill actively builds a ubiquitous language during planning, making communication between developer and agent more precise and reducing token waste. This treats the project's domain model as a first-class, evolving artifact.

Frequently Asked Questions (FAQ)

1. What is the difference between Skills and GitHub Copilot? GitHub Copilot is an AI-powered code completion tool that suggests lines or blocks of code inline. Skills is a set of high-level prompt-based workflows for AI coding agents (which may use Copilot) that orchestrate entire engineering disciplines like planning, testing, debugging, and architecture. Skills operates at the workflow level, not the autocomplete level.
2. How do I install and use Skills with my AI coding agent? You can install Skills via the skills.sh installer (npx skills@latest add mattpocock/skills) to copy editable skill files into your project, ideal for customization. Alternatively, for Claude Code, you can install it as a managed plugin (/plugin install mattpocock-skills@mattpocock) for automatic updates. After installation, run /setup-matt-pocock-skills once per repository to configure your issue tracker and documentation paths.
3. Can I use Skills with AI agents other than Claude Code? Yes. The Skills repository adheres to the Agent-Skills standard, making it compatible with any coding agent that supports this standard. The skills.sh installer is designed to deploy these skills into various compatible harnesses.
4. Is Skills suitable for beginner programmers? Skills is optimized for "Real Engineers" and assumes familiarity with professional software engineering concepts like TDD, refactoring, and system design. While beginners can use it, they will gain the most value if they are looking to learn and apply these professional practices through AI collaboration.
5. How does Skills handle project management and ticketing? Skills integrates with your existing workflow. The /to-tickets skill can output tickets as text files or create native issues with blocking links in connected trackers like GitHub Issues or Linear. This allows you to maintain your preferred project management system while using AI to break down and track work.