The Right Way to Write an Agent Skill
A practical guide to writing better AI agent skills, with principles for routing, procedure design, scripts, verification, and feedback loops.
Writing effective agent skills involves adhering to a set of principles. First, the description serves as a router, providing a way to identify when the skill should be used based on the words a user types. Second, the body of the skill consists solely of steps, with any non-step content removed. The scripts handle fixed sequences of actions, while the agent manages judgment calls.
Third, it's important to distinguish between scripts and judgement; scripts should manage deterministic actions, while the agent deals with logical reasoning required for complex tasks. In the bad example, the agent is responsible for both actions and decision-making, leading to inefficiency. In contrast, the good example places scripts in charge of clear, deterministic steps, and entrusts the agent with judgement calls.
Finally, SKILL.md should only contain information that every execution of the skill requires, minimizing the amount of context loaded before the agent begins processing the task.
Written by urgent.news from HackerNoon's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
