Matt Pocock Shares Writing Great Skills Guide for Predictable AI Agents

Matt Pocock published a practical guide called Writing Great Skills to help teams create AI skills that behave consistently instead of surprising users mid-task.

The guide centers on one goal: make the process itself predictable so models stay focused and finish work without extra supervision. It draws from real usage patterns in agent workflows where skills get called dozens of times per day.

Teams working with AI agents now face pressure to reduce random failures. Pocock's approach addresses that pressure directly by separating two types of skills and enforcing strict structure inside each one.

Skill Types Split Model Triggers From User Commands

Pocock first requires writers to label every skill as either model-invoked or user-invoked. Model-invoked skills run automatically when the model decides the condition is right. User-invoked skills only run after a person explicitly calls them.

The distinction matters because the description field works as the actual trigger text for model-invoked skills. Vague descriptions cause the model to fire at the wrong moment or skip the skill entirely. Clear trigger language in the description keeps behavior stable across repeated calls.

Three Layer Structure Limits Context Drift

Each skill uses a strict three-layer format. The first layer lists the main steps with a single completion check at the end of every step. The second layer holds supporting references the model can consult without leaving the main flow. The third layer points to external files only when the first two layers prove insufficient.

This structure enforces progressive disclosure. The model sees only what it needs at each moment, which reduces attention dilution that occurs when every instruction lives in one long block. Teams report fewer cases of the model skipping steps or repeating work after adopting the format.

Leading Words Replace Long Instructions

Pocock recommends compressing requirements into a few leading words at the start of each step. Instead of writing several sentences about expected output format, writers place the expected outcome word first, followed by the action. The model receives the constraint immediately and spends fewer tokens on interpretation.

Five Failure Modes Receive Explicit Checks

The guide lists five common failure patterns and supplies a test for each. Premature completion happens when the model claims a task is done before all steps pass their completion criteria. Duplication appears when the same output is produced more than once in one run. Sediment builds up when old context from previous calls leaks into the current skill. Sprawl occurs when the model pulls in related but unnecessary tasks. No-op triggers when the model skips the skill without producing any output.

Writers test for No-op by asking whether every sentence in the skill contains an observable action or decision. Sentences that describe state without forcing change are removed or rewritten.

Split Skills Keep Model Attention Narrow

Large monolithic skills spread attention too thin. Pocock advises breaking complex work into smaller skills that each own one clear outcome. Narrow scope lets the model track completion criteria more accurately and makes it easier to debug which skill introduced an error.

The same principle applies to context length. Each additional paragraph increases the chance the model will drift. By keeping skills short and layered, teams reduce the surface area for drift without sacrificing necessary information.

Early Adopters Report Fewer Surprise Outputs

Developers who adopted the guide early describe fewer instances of agents finishing with incomplete artifacts. One team using the three-layer format inside their internal code review skill cut average review time by roughly a quarter because the model stopped suggesting unrelated refactors.

Another group integrated the No-op test into their skill review checklist before deploying new agent capabilities. They found the test caught vague instructions that previously led to silent failures in production.

Limits Remain Around Long Running Tasks

Pocock notes that skills still struggle when tasks span many minutes or require coordination across external systems that return results asynchronously. The current structure helps with short, contained workflows but does not yet solve state management across long sessions.

Teams facing that constraint continue to add lightweight wrapper skills that poll for results rather than relying on a single large skill to handle the full sequence.

Next Milestones Focus on Tooling and Shared Libraries

The next signals to watch are whether public skill libraries begin publishing templates that follow the three-layer format and whether diagnostic tools appear that automatically flag No-op sentences. Both developments would indicate the approach is moving from individual practice to shared infrastructure.