Composable Agent Skills for Real Engineering Workflows
Matt Pocock's personal agent skills for Claude Code and Codex, targeting four common failure modes in AI-assisted development: misalignment, verbosity, broken code, and design entropy. Instead of controlling the process, these small, composable skills embed engineering fundamentals—grilling sessions for alignment, shared ubiquous language for concision, TDD red-green-refactor loops for code quality, and architecture rescue tools. They work with any model and are designed to be hacked and adapted in your own .claude directory.
This is a collection of lightweight, composable skills designed for coding agents like Claude Code or Codex. It’s not vibe coding. Each skill encodes battle-tested software engineering practices—grilling sessions, shared language, red-green-refactor loops—into repeatable commands so that AI-assisted development stays aligned, correct, and maintainable.
这是一套为 Claude Code、Codex 等编码 Agent 设计的轻量级、可组合技能集合。它不是“氛围编程”。每个技能都将久经验证的工程实践——如“盘问式对齐”、“共享语言”、“红-绿-重构循环”——封装成可重复的命令，确保 AI 辅助开发始终保持方向一致、代码正确且架构可维护。
The repository identifies four fundamental failure modes in agent-assisted development: 1) misalignment between developer intent and agent output, 2) verbose, jargon-ridden communication, 3) broken code from lack of tight feedback loops, and 4) rapid codebase entropy leading to a “ball of mud”. Each skill in this repo directly targets one or more of these problems.
仓库识别了 Agent 辅助开发中的四种根本性失效模式：1) 开发者意图与 Agent 产出之间的错位；2) 冗长、充满行话的沟通；3) 因缺乏紧密反馈循环而产出无法运行的代码；4) 代码库熵增极快，迅速变成“泥球”。仓库中每个技能都直接瞄准其中一个或多个问题。
Two key design pillars stand out. First, /grill-me and /grill-with-docs force the agent to become a relentless interviewer, drilling into your plan until every edge case is exposed. This upfront alignment prevents costly misunderstandings. Second, /grill-with-docs captures this discussion into a CONTEXT.md file, creating a shared, domain-specific glossary. This shared language drastically reduces token waste and improves naming consistency across the project.
两个核心设计支柱尤为突出。第一，/grill-me 和 /grill-with-docs 强制 Agent 扮演无情的面试官，对你的计划刨根问底，直到所有边界情况都暴露无遗。这种前置对齐能避免代价高昂的误解。第二，/grill-with-docs 将讨论结果捕获到 CONTEXT.md 文件中，创建一个共享的、领域特定的术语表。这种共享语言能极大减少 token 浪费，并提升整个项目中命名的统一性。
To ensure the code actually works, the skills enforce tight feedback loops. /tdd guides the agent through a strict red-green-refactor cycle, writing failing tests before implementation. /diagnose provides a structured debug loop: replicate → minimize → hypothesize → instrument → fix → regression-test. These steps ground the agent in concrete execution results rather than hallucinations.
为确保代码真正可用，这些技能强制实施了紧密的反馈循环。/tdd 引导 Agent 执行严格的红-绿-重构循环，在实现代码前先写失败的测试。/diagnose 提供了一个结构化的调试循环：复现 → 最小化 → 假设 → 插桩 → 修复 → 回归测试。这些步骤将 Agent 锚定在具体的执行结果上，而非幻觉。
These skills are not a framework, but a set of markdown files (SKILL.md) that define slash commands for the agent. The repository structure separates them into skills/engineering, skills/productivity, and skills/misc. An installer (npx skills@latest add mattpocock/skills) scaffolds them into the local agent’s directory. A first-run /setup-matt-pocock-skills command then tailors the skills to your project by asking about issue trackers, triage labels, and document storage locations.
这些技能不是框架，而是一组定义了 Agent 斜杠命令的 markdown 文件（SKILL.md）。仓库结构将它们分为 skills/engineering、skills/productivity 和 skills/misc。安装器（npx skills@latest add mattpocock/skills）将它们脚手架化到本地 Agent 目录中。首次运行 /setup-matt-pocock-skills 命令则会通过询问你的问题追踪器、分类标签和文档存储位置，将技能适配到你的具体项目。
To use these skills, first add them to your agent:
npx skills@latest add mattpocock/skills
During installation, select the skills you want and your target agents. Ensure you include /setup-matt-pocock-skills.
Next, run the setup command inside your agent:
/setup-matt-pocock-skills
This interactive command will configure the issue tracker, triage labels, and the document directory, after which all other skills are ready to use.
要使用这些技能，首先将它添加到你的 Agent：
npx skills@latest add mattpocock/skills
安装过程中，选择你需要的技能和目标 Agent。务必勾选 /setup-matt-pocock-skills。
接着，在 Agent 内部运行初始化命令：
/setup-matt-pocock-skills
这个交互式命令会配置问题追踪器、分类标签和文档存储目录，完成后所有技能即可使用。
The skills/engineering directory contains commands for the whole development cycle. to-prd synthesizes a PRD from the conversation and files a GitHub issue. to-issues breaks it into vertical-slice issues. triage manages issues through a state machine. tdd enforces a test-first workflow, and diagnose hunts bugs systematically. A crucial maintenance command is improve-codebase-architecture, which is recommended to run every few days to find “deepening” opportunities.
skills/engineering 目录包含覆盖整个开发周期的命令。to-prd 从对话中合成 PRD 并提交 GitHub issue。to-issues 将其分解为垂直切片的 issue。triage 通过状态机管理这些 issue。tdd 强制测试先行，diagnose 系统性地追查 bug。一个关键的维护命令是 improve-codebase-architecture，建议每隔几天运行一次，以发现让架构“深化”的机会。
These skills are ideal for disciplined, long-lived software projects where code quality, domain complexity, and maintainability are primary concerns. They are particularly effective when paired with Claude Code or Codex. Caveats: The skills are opinionated toward GitHub/Linear issue trackers and manually defined triage labels. They also assume the user is comfortable running slash commands and maintaining a CONTEXT.md. They are not a one-shot project generator; they shine in iterative, day-to-day engineering work.
这些技能非常适合那些将代码质量、领域复杂性和可维护性放在首位的，有纪律的长期软件项目。它们与 Claude Code 或 Codex 等 Agent 搭配效果尤其好。需要注意的边界是：技能集对 GitHub/Linear 问题追踪器和手动定义的分类标签有较强的偏好，且假设用户愿意运行斜杠命令并维护 CONTEXT.md 文件。它不是一次性的项目生成器，而是在迭代的、日常的工程工作中才能大放异彩。