/agent

wiki / raw / mattpocock-skills-repo-2026

mattpocock/skills: Skills for Real Engineers

updated 2026-08-22

Original source: https://github.com/mattpocock/skills SHA256: 1a38fb49eb8ebbaf1c4397d21232a405ba8565744e0c8306cf5beec4f94b4224

mattpocock/skills: Skills for Real Engineers

Author: Matt Pocock
Repository: https://github.com/mattpocock/skills
Description: Modular skill system for coding agents (.agents / .hermes / .claude), codifying human software engineering discipline into machine-executable routines.

Core Thesis & Philosophy

  • The AI Dilemma: Approaches like GSD, BMAD, and Spec-Kit attempt to own the whole engineering process, removing developer control and making process bugs hard to diagnose.
  • Root Problem: Bad code is the most expensive it has ever been. Autonomous agents generate high volume; without disciplined feedback loops, they create architectural “balls of mud”, degrade the context window, and cause subsequent agent iterations to fail.
  • Fundamentals Matter More: Good software engineering practices (small interfaces, deep modules, test-driven development, continuous domain modeling) are essential guardrails for AI agents.

Skill Architecture & Invocation Models

Skills are split by invocation mechanics:

  1. User-Invoked Skills: Interactive orchestration workflows explicitly triggered by the human (e.g. /grill-me, /to-spec, /to-tickets, /implement, /wayfinder, /ask-matt). They can invoke model-invoked skills, but never other user-invoked ones.
  2. Model-Invoked Skills: Procedural and disciplined subroutines that can be triggered automatically by the agent or explicitly by the human (e.g. /tdd, /diagnosing-bugs, /domain-modeling, /codebase-design, /code-review, /grilling, /writing-for-agents).

The Four Core Failure Modes & Skill Solutions

  1. The Agent Didn’t Do What I Want: Solved via relentless requirement sharpening (/grill-me, /grill-with-docs) before code is written.
  2. The Agent Is Too Verbose: Solved via disciplined domain modeling (/domain-modeling, CONTEXT.md) so variable names, concepts, and interfaces are concise and unambiguous.
  3. The Code Doesn’t Work: Solved via automated feedback loops (/tdd with red-green-refactor, /diagnosing-bugs root-cause investigation).
  4. We Built A Ball Of Mud: Solved via deep module architecture principles (John Ousterhout, A Philosophy of Software Design), pre-spec module quizzing (/to-spec), and proactive architectural audits (/improve-codebase-architecture).