# Building Better AI Agent Skills: The Missing Manual _Matt Pocock shares his framework for building effective AI agent skills, covering triggers, structure, steering, and pruning, and offering tips to avoid common pitfalls._ **Updated:** 2026-08-22 **Published:** 2026-06-29 **Source:** https://www.startuphub.ai/ai-news/artificial-intelligence/2026/building-better-ai-agent-skills-the-missing-manual --- In the rapidly evolving world of AI agents, the ability to build and refine agent skills is paramount. Matt Pocock, a prominent figure in this space, recently shared his insights in a video titled "Building Great Agent Skills: The Missing Manual." Pocock, known for his contributions to the AI developer community, outlines a practical framework for creating effective and efficient agent skills, addressing common pitfalls developers encounter. Skill Hell ProblemDriveroverwhelming cycle of learning skills without effective integrationFrom the article 2 mentionsPocock begins by identifying a common challenge developers face: "Skill Hell." This refers to the overwhelming cycle of trying to learn numerous skills and frameworks, only to struggle in integrating them effectively.leads toMissing ManualDriverlack of a clear rubric for what constitutes a great skillFrom the article 2 mentionsPocock's "Missing Manual" provides a valuable roadmap for anyone looking to build more effective AI agents.addressed bySkill ChecklistContextprovides a defined rubric for building effective AI agent skillsFrom the article 9+ mentionsTo combat this, Pocock proposes a "Skill Checklist" that breaks down the essential components of a well-crafted agent skill.guided byFramework PrinciplesContextcovers triggers, structure, steering, and pruning for great skillsFrom the article 4 mentionsHe likens it to "Tutorial Hell" and "Framework Hell," where developers get stuck in a loop of consuming information without achieving practical mastery.User vs. ModelContextdistinguishes between skill invocation types for clarityFrom the article 3 mentionsModel-invoked skills, conversely, are triggered by the AI model itself based on context.Avoid PitfallsEffecttips to prevent common challenges in skill developmentFrom the article 3 mentionsEnsure each piece of information has a single source of truth to avoid confusion and redundancy.Better AI Agent SkillsEffectenables more effective and efficient AI agent capabilitiesFrom the article 9+ mentionsPocock outlines several key tips for building better agent skills: ## The Core Problem: Skill Hell Pocock begins by identifying a common challenge developers face: "Skill Hell." This refers to the overwhelming cycle of trying to learn numerous skills and frameworks, only to struggle in integrating them effectively. He likens it to "Tutorial Hell" and "Framework Hell," where developers get stuck in a loop of consuming information without achieving practical mastery. The fundamental issue, according to Pocock, is the lack of a clear understanding of what truly constitutes a "great skill." Without a defined rubric or framework, developers often find themselves unable to differentiate between effective and ineffective skills, leading to inefficient development and suboptimal agent performance. ## The Missing Manual: A Skill Checklist To combat this, Pocock proposes a "Skill Checklist" that breaks down the essential components of a well-crafted agent skill. This checklist includes four key areas: - **Trigger:** How the skill is invoked. - **Structure:** The internal organization of the skill. - **Steering:** How the skill is guided to perform specific actions. - **Pruning:** The process of refining and removing unnecessary or outdated elements. He emphasizes that the trigger mechanism determines when a skill is activated, while structure dictates how it's built and organized. Steering involves guiding the agent to use the skill effectively, and pruning ensures the skill remains relevant and efficient over time. ## User-Invoked vs. Model-Invoked Skills A critical distinction Pocock highlights is between user-invoked and model-invoked skills. User-invoked skills are directly called by the user, offering greater control and predictability. Model-invoked skills, conversely, are triggered by the AI model itself based on context. Pocock expresses a preference for user-invoked skills due to their inherent predictability and reduced "cognitive load" on the user. He contrasts his own skill repository, `matpocock/skills`, with another popular one, `obra/superpowers`, noting that while both are effective, the former prioritizes user-invoked skills. This distinction is important because model-invoked skills, while powerful, can introduce unpredictability and increase the computational cost (token usage) for the agent. ## Key Principles for Great Skills Pocock outlines several key tips for building better agent skills: - **Tip 1: Decide if your skill is user-invoked or model-invoked.** This decision impacts predictability and control. User-invoked skills generally offer more direct control, while model-invoked skills can be more autonomous but potentially less predictable. - **Tip 2: Structure skills into steps and reference.** Each skill should have a clear, step-by-step procedure and supporting reference material. This modularity enhances understanding and maintainability. - **Tip 3: Make SKILL.md as small as possible.** Concise skill descriptions reduce complexity and improve the agent's ability to quickly process and utilize the information. - **Tip 4: Hide branching reference material behind context pointers.** This keeps the primary skill definition clean while allowing access to more detailed information when needed. - **Tip 5: Use consistent leading words.** Leading words, like "vertical slice," act as reasoning tokens that guide the agent's behavior and output, making it more predictable. - **Tip 6: Increase legwork by hiding future steps.** By not revealing the entire plan upfront, you encourage the agent to focus on the current step and perform more thorough, relevant legwork. - **Tip 7: Don't repeat yourself.** Ensure each piece of information has a single source of truth to avoid confusion and redundancy. - **Tip 8: Use the deletion test.** Regularly prune or delete irrelevant skills to maintain efficiency and prevent "sediment" buildup in the agent's knowledge base. ## Conclusion Pocock's "Missing Manual" provides a valuable roadmap for anyone looking to build more effective AI agents. By focusing on clear triggers, structured organization, deliberate steering, and consistent pruning, developers can move beyond the common pitfalls of "skill hell" and create agents that are not only powerful but also reliable and efficient. --- Original analysis from [startuphub.ai](https://www.startuphub.ai), the #1 AI startup directory. © StartupHub.ai. All rights reserved. You may not republish this article in full without a license. Search engines and AI research tools may crawl and summarize for reference. Bulk reproduction or model training on this content requires a license. See https://www.startuphub.ai/terms.