The Framework for High-Quality Skills

To avoid "skill hell"—a state where developers accumulate numerous, poorly understood, and uncoordinated agent skills—builders should adopt a structured rubric. This framework focuses on four pillars: Trigger, Structure, Steering, and Pruning.

1. Trigger: Balancing Context vs. Cognitive Load

Deciding how a skill is invoked is a fundamental design choice:

  • Model-Invoked Skills: These allow the agent to self-select tools. While flexible, they increase "context load" by adding descriptions to the agent's context window, which costs tokens and introduces unpredictability.
  • User-Invoked Skills: These require the human pilot to trigger the skill. While this increases the user's cognitive load, it provides greater control and eliminates the unpredictability of an agent choosing not to follow a context pointer.

2. Structure: Minimizing the Skill File

Keep the skill.md file as small as possible to reduce token costs and maintenance friction.

  • Units of Composition: Organize skills into two units: steps (procedures) and reference (supporting info).
  • Branching Logic: If reference material is only needed for specific branches of a skill, move it out of the main skill.md and hide it behind context pointers (separate files). This ensures the agent only pulls in necessary information for the specific path it is currently executing.

3. Steering: Leading Words and Leg Work

Steering is the art of ensuring the agent performs as expected.

  • Leading Words: Use specific, high-density terms (e.g., "vertical slice") to guide the agent. Because agents repeat these words in their reasoning traces, they reinforce the desired behavior throughout the task.
  • Increasing Leg Work: If an agent rushes through a step (like planning) to reach the final goal, break the process into smaller, individual skills. By hiding future steps from the agent, you force it to focus entirely on the current phase, increasing the quality of the output for that specific step.

4. Pruning: Removing Sediment and No-Ops

Maintenance is critical to prevent skill bloat.

  • Single Source of Truth: Avoid duplicating information across steps or reference files.
  • Sediment Removal: Regularly audit shared markdown files to remove legacy or irrelevant material that accumulates over time.
  • No-Op Elimination: Perform "deletion tests" on your instructions. If you remove a paragraph and the agent's behavior remains unchanged, that instruction is a "no-op" and should be deleted to save context space.