Building Great Agent Skills: The Missing Manual

The central problem with agent skills is not scarcity. Developers can download, contribute to, and assemble many different skills, yet still struggle to understand how those pieces work together or distinguish effective skills from ineffective ones. Pocock calls this condition skill hell: an accumulation of apparent capabilities that does not reliably produce the promised results. 0:00

The problem extends beyond individual developers. Organizations may have operating procedures they want agents to perform, but without a clear understanding of how to translate those procedures into effective skills, the availability of skills does not automatically become operational value. The missing ingredient, Pocock argues, is a shared rubric for assessing what makes a skill work. 0:51

His proposed rubric has four parts: trigger, which determines how a skill is invoked; structure, which governs how its instructions and supporting material are organized; steering, which shapes agent behavior; and pruning, which removes unnecessary material after the skill works. Together, these categories turn skill quality into a set of concrete design decisions instead of a vague judgment about whether a prompt seems useful. 1:50

A skill can be invoked explicitly by its user, or it can be made available for the model to select on its own. For model-invoked skills, the skill description enters the agent’s context and acts as a context pointer: the agent can use that description to decide whether to read the associated skill.md file. A skill can instead omit that model-visible pointer, making it available only when the user deliberately invokes it. 3:28

Model invocation increases convenience, but that convenience has a recurring cost. Every model-visible skill adds another description to the context, consuming tokens on requests and presenting the agent with another option to consider. Pocock describes this as context load. If an environment contains 100 model-invoked skills, the agent must carry 100 corresponding descriptions. 5:17

User invocation shifts that burden away from the agent and onto the person operating it. The agent receives less ambient context, but the user must remember which skills exist and recognize when to call them. Pocock describes this opposing cost as cognitive load and contrasts the primarily model-invoked orientation of superpowers with his preference for directly controlling when his own skills run. 5:17

There is also a reliability tradeoff: a model may decline to follow a context pointer even when its associated skill appears well suited to the task. Pocock prefers explicit invocation because it removes that particular uncertainty and avoids having to evaluate whether the model selects skills at the intended moments. However, he does not present either invocation style as universally superior; each relocates cost and responsibility. 6:16

Pocock breaks most skills into two basic units: steps and reference. Steps describe the procedure the agent should follow, while references provide the information needed to carry out that procedure. A skill can consist entirely of one category, but identifying the distinction makes it easier to determine what belongs in the workflow and what merely supports it. 7:22

His 2PRD skill illustrates the pattern. Its procedure finds relevant context, confirms test seams with the user, and writes a product requirements document. The confirmation step creates a human checkpoint around testing. Supporting those steps are two references: an explanation of what a test seam is and a product requirements document template. 7:22

The main skill.md file should remain as small as the task permits because shorter skills are easier to maintain, audit, and load into context. The key structural question is whether a piece of reference material is needed every time. In 2PRD, the PRD template and test-seam explanation align with a single recurring workflow, so Pocock treats both as reasonable candidates to remain inside the main file. 8:24

A branching workflow calls for a different arrangement. Pocock’s domain modeling example may update a local glossary named context.md, create architectural decision records, or do neither. Since the associated templates are not universally required, they can live in separate files bundled with the skill. The main skill.md then uses conditional context pointers to load each external reference only when its branch becomes relevant. 9:28

A skill can state an intended outcome and still fail to produce the desired behavior. Pocock’s primary steering technique is to use leading words: compact terms or phrases that carry substantial meaning and can recur throughout the skill. His proposed mechanism is that the agent repeats those terms in its reasoning and output, reinforcing the intended approach as it works. 11:29

His example addresses an agent that implements software horizontally, completing the database, schemas, API endpoints, and frontend as separate layers. Rather than relying only on a lengthy warning against that pattern, the skill can consistently emphasize vertical slice. That phrase directs attention toward getting a small end-to-end implementation working before expanding it, and its appearance in reasoning traces offers a practical signal that the agent has adopted the intended framing. 12:23

The value of leading words depends on consistency rather than reducing an entire skill to a slogan. Pocock recommends repeating concise, meaningful terminology throughout the instructions and experimenting with stronger alternatives when behavior remains misaligned. Agents can also help generate candidate phrases, but the important test is whether the terminology actually appears in the agent’s work and changes the resulting plan. 13:15

A separate steering problem arises when an agent rushes through an intermediate phase because it can already see its final objective. Pocock observes this in plan mode: the agent asks a few clarifying questions and then quickly produces a plan. His alternative separates clarification into a skill called grill with docs and follows it with 2PRD, so the agent sees only the current phase. Hiding later steps can increase leg work where deeper investigation matters, although he explicitly notes that splitting every skill into individual phases is unnecessary. 14:15

Once a skill works, its remaining size becomes an object of scrutiny. Pocock treats oversized skills as a symptom that other design failures may be present rather than as a useful property in itself. The first corrective is single source of truth: procedural instructions, templates, and definitions should not be duplicated across steps or supporting reference material. 16:18

Another failure mode is sediment, the gradual buildup that occurs when multiple contributors keep adding material to a shared markdown file without removing or reorganizing earlier contributions. The remedy begins with structure: determine whether each addition applies to every branch, move branch-specific information into the relevant external reference, and remove material that is irrelevant or stale. 17:07

The final target is the no-op: an instruction that looks useful but does not meaningfully change what the agent would have done anyway. Pocock gives the example of a paragraph demanding a long, detailed commit message when the agent might produce an adequate message without that paragraph. A practical deletion test asks what changes if the instruction disappears; if behavior remains effectively unchanged, the text may not justify its context cost. 18:05

The complete review returns to the same four questions: whether the trigger balances context load against cognitive load, whether the structure separates steps from branch-specific references, whether leading words and phase boundaries produce the intended behavior, and whether pruning removes duplication, sediment, and no-ops. Pocock presents this as a repeatable framework for improving existing skills and evaluating community-authored ones before relying on them. 19:03