Building Great Agent Skills: The Missing Manual

Key Concepts

• Skill Hell: A state where developers struggle to integrate numerous available AI skills, unable to distinguish between high-quality and low-quality implementations, leading to poor results.
• User-Invoked vs. Model-Invoked Skills: The distinction between skills triggered manually by a human versus those triggered autonomously by an AI agent based on a description.
• Context Load: The burden placed on an AI agent’s context window by including too many skill descriptions, which increases token costs and potential for confusion.
• Cognitive Load: The mental effort required by the human user to manage and remember how to invoke various skills.
• Leading Words: A technique of using specific, high-meaning terminology to steer an agent’s reasoning and output.
• No-ops: Instructions within a skill that appear to do something but have no actual influence on the agent's behavior.
• Sediment: Irrelevant or stale information that accumulates in skill files over time as multiple contributors add content without pruning.

---

1. The Skill Checklist Framework

To escape "Skill Hell," the speaker proposes a four-part rubric for evaluating and writing effective AI skills:

I. The Trigger (Invocation)

• User-Invoked: The skill is manually called. It keeps the agent's context window clean but increases the user's cognitive load.
• Model-Invoked: The agent decides when to use the skill based on a description. This increases "context load" (token usage) and introduces unpredictability, as the model may fail to trigger the skill even when appropriate.
• Recommendation: Decide based on whether you prefer to manage the agent's context (User-Invoked) or the user's mental effort (Model-Invoked).

II. Internal Structure

• Steps: The procedural, step-by-step instructions for the agent.
• Reference: Supporting information (templates, definitions) required to execute the steps.
• Optimization: Keep the skill.md file as small as possible. If a skill has multiple branches (e.g., a "Domain Modeling" skill that does different things), move branch-specific reference material into separate files accessed via context pointers (links to external files) rather than bloating the main file.

III. Steering (Agent Behavior)

• Leading Words: Use industry-standard, high-density terminology (e.g., "Vertical Slice") to guide the agent. The agent will incorporate these words into its internal reasoning traces, effectively "thinking" in the desired framework.
• Leg Work: If an agent rushes through a task (e.g., planning), split the skill into smaller, sequential skills. By hiding future steps from the agent, you force it to focus entirely on the current phase, increasing the quality of the output.

IV. Pruning (Maintenance)

• Single Source of Truth: Ensure reference material is not duplicated across the skill.
• Sediment Removal: Regularly audit skills to remove stale or irrelevant content added by multiple contributors.
• Deletion Tests: Identify "no-ops"—sections of the skill that, if deleted, would not change the agent's output. If a section doesn't change behavior, remove it to save tokens and reduce noise.

---

2. Real-World Applications & Examples

• 2PRD Skill: A tool for creating Product Requirements Documents. It uses three steps (find context, confirm test seams, write PRD) and two references (test seam definition, PRD template).
• Domain Modeling Skill: An example of a multi-branch skill. Because it performs different actions (updating a glossary vs. creating architectural decision records), the speaker uses external references to keep the main skill.md lean.
• Grill with Docs: A specific implementation of the "Leg Work" strategy where the agent is forced to perform deep questioning before it is allowed to see the "Plan" skill, preventing premature planning.

---

3. Key Arguments

• The Cost of Unpredictability: The speaker argues against over-relying on model-invoked skills because they introduce a "class of problem" where the model may ignore the skill, necessitating complex evaluation (evals) to ensure reliability.
• Small is Better: Smaller skills are easier to audit, maintain, and cheaper to run. Every word removed from a skill is a token saved on every execution.
• Consistency: The effectiveness of "Leading Words" relies on the user consistently using the same terminology across their skill set, allowing the agent to build a reliable pattern of behavior.

---

4. Synthesis

To write great skills, developers must move away from "Skill Hell" by treating skills as modular, lean, and highly specific units of logic. By balancing the trigger mechanism, structuring content into steps and external references, using "leading words" to steer reasoning, and ruthlessly pruning "no-ops" and sediment, developers can create predictable, high-performing agents. The speaker encourages users to apply this framework using his "Writing Great Skills" repository to audit and improve their existing toolsets.