Writing Skills

Creating a new skill for an AI agent follows a clear process. You start by writing test cases that challenge the agent. Then you watch the agent fail without the skill. This shows you exactly what needs to be taught. Next you write the skill as documentation. After that you run the tests again to see if the agent now follows the rules. Finally you close any loopholes. This cycle is called RED-GREEN-REFACTOR. It comes from Test-Driven Development adapted for documentation. The core idea is simple. If you never saw the agent fail without the skill you cannot be sure the skill works. This approach helps anyone create reliable skills for AI agents.

Skills are reference guides for proven techniques or tools. They are not stories about a problem you solved once. A good skill teaches future agents how to handle common situations. You can create a skill for a technique, a pattern, or a reference. Each skill lives in its own folder with a main file called SKILL.md. The name and description go in the front matter. The description should say when to use the skill, not what it does.