Fix communication gaps with coding agents using this practical workflow collection
If you have experienced agents misunderstanding requirements, providing unnecessarily long explanations, or producing messy code, this repository may be the answer. It is a skill set designed to address common failure patterns that occur when coding agents perform actual engineering tasks. Each skill is small, composable, and not tied to a specific model, allowing you to freely modify and refine them to fit your own style.
Design targeting agent failure patterns
The author focuses on solving four common problems encountered when using coding agents. First, to address the issue of agents not accurately understanding user intent, /grill-me and /grill-with-docs are provided. These skills conduct a 'grilling session' before development begins, where the agent asks detailed questions to clarify requirements. Second, to solve the problem of agents not knowing project terminology and using too many words, a shared language document is built. This allows the agent to use project-specific terms instead of complex explanations, generating more concise and accurate responses. Third, to prevent code from not actually working, /tdd and /diagnosing-bugs are used to strengthen the feedback loop. Finally, to prevent software entropy from increasing as agents generate code quickly, /improve-codebase-architecture is used to regularly check the structural depth of the codebase.
Distinction between user-invoked and model-invoked skills
The skills in this repository are divided into two types based on who can invoke them. User-invoked skills only work when the user directly inputs a command and primarily serve to orchestrate workflows. For example, /grill-me and /triage must be explicitly executed by the user. In contrast, model-invoked skills can be executed directly by the user, but also contain reusable disciplines that the agent can automatically invoke if it determines they fit the work context. /tdd and code-review fall into this category, and user-invoked skills can call model-invoked skills but cannot call other user-invoked skills. This structure allows for managing complex workflows while enabling the agent to use appropriate tools at the right time.
Installation methods and initial setup
Installation is done in two ways, each following a different philosophy. The first is installing the Claude Code plugin, which installs the entire skill set as a read-only bundle, providing a subscription-style method that automatically receives the author's updates. The second is copying editable skill files to the project via skills.sh, allowing you to directly modify and customize the files. If both methods are installed simultaneously, all skills will be duplicated, so you must choose only one. After installation, run /setup-matt-pocock-skills to configure the issue tracker (GitHub, Linear, local files), triage labels, and document storage location to complete the setup. This configuration only needs to be performed once per repository.
Considerations before application
This skill set is suitable for developers who use coding agents daily and is particularly useful for those who want to improve communication efficiency with agents. However, since the skills significantly change how the agent operates, you should check for potential conflicts with existing workflows. Additionally, maintaining CONTEXT.md and ADR (Architecture Decision Record) documents is required, which may involve an initial learning curve. Although the README states that it is not dependent on specific models or frameworks, it mentions Claude Code and Codex as primary targets, so compatibility with other agents must be tested directly. Finally, since skill files are editable, they provide greater value to users willing to modify them to fit their project's characteristics.
