← back
Building Great Agent Skills: The Missing Manual
Takeaway
Design skills deliberately around invocation tradeoffs, clear procedures, useful references, and minimal context.
Summary
- Matt Pocock proposes evaluating skills through four dimensions: trigger, internal structure, steering, and minimal size.
- Model-invoked skills add persistent descriptions to context and introduce uncertainty about whether the agent will follow the pointer.
- User-invoked skills reduce automatic context overhead but require users to remember which skills to call.
- Separate procedural steps from reference material, then prune irrelevant instructions and no-ops.
agent-skillscontext-engineeringskill-design
Original description
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/...