Building Great Agent Skills: The Missing Manual

Let's discuss how to navigate "skill hell" by providing a structured framework for building high-quality agent skills. Without a shared rubric, developers and organizations struggle to create effective, maintainable skills for AI agents.

Timestamps:

0:00 - Introduction to the talk and the concept of "skill hell"
2:12 - Overview of the skill checklist framework
3:16 - Trigger: Choosing between user-invoked and model-invoked skills
7:29 - Structure: Organizing steps and references
9:00 - Making the skill.md file minimal
11:54 - Steering: Using leading words to guide agent behavior
14:56 - Increasing "leg work" per step
16:48 - Pruning: Removing sediment, crud, and no-ops
19:06 - Final summary of the checklist framework
19:55 - Where to find the "writing great skills" resource

The Skill Checklist Framework:

Trigger (3:16 - 7:25): Decide whether a skill should be user-invoked or model-invoked. Matt notes that while model-invoked skills offer more flexibility, they increase context load and introduce unpredictability. User-invoked skills offer more control but require greater cognitive load from the pilot.

Structure (7:29 - 11:53): Organize your skill into two primary units: steps (procedures) and reference (supporting information). To keep the skill.md file minimal, move branching reference material behind context pointers to reduce bloat and maintenance costs.

Steering (11:54 - 16:47): Use leading words—specific terms that pack dense meaning—to influence agent behavior and guide reasoning traces. Additionally, you can force the agent to perform more "leg work" on specific tasks by breaking complex processes into smaller, individual skills that hide future steps.

Pruning (16:48 - 19:05): Maintain a clean skill set by ensuring a single source of truth, removing "sediment" (irrelevant legacy material), and eliminating "no-ops" (instructions that don't actually change agent behavior).

https://github.com/mattpocock/skills/blob/main/skills/productivity/writing-great-skills/SKILL.md