How to Write Your First Agent ... Note

How to Write Your First Agent Skill

The provided text explains the concept of "skills" for AI coding agents, which are essentially structured instruction sets. These skills are designed to overcome the problem of AI agents forgetting instructions over successive sessions. A skill is defined as a folder containing a single file named SKILL.md. This file has two distinct parts:YAML frontmatter and a markdown body.The YAML frontmatter includes a "name" and a "description." The description is crucial as it acts as the trigger for the agent, informing it when a particular skill is relevant to the user's request. The markdown body contains the actual instructions for the skill, including the workflow, rules, and an example. This body should be plain markdown and avoid code or configuration beyond the frontmatter.The text then illustrates this concept with a "teardown" example of a commit-message skill. This skill's frontmatter clearly defines its purpose and trigger. The workflow outlines a five-step process for generating commit messages, including a stop condition. Rules are provided to enforce judgment calls, such as separating the subject and body's purpose and avoiding meta-commentary.An example demonstrates the expected output, and anti-patterns highlight common failure modes to be avoided. The text emphasizes that each part of the skill serves a specific purpose: description for triggering, steps for execution order, rules for judgment, example for format, and anti-patterns for refusals. To create a new skill, one should first write the description, then the numbered workflow steps with stop conditions, followed by judgmental rules, a concrete example, and finally, explicit anti-patterns.The key principle is to keep skills concise and focused, with rules only included if they are actively used. Skills are deployed by placing their folders into the agent's skill directory, after which the agent automatically recognizes and uses them based on their descriptions. The text also provides a link to a repository with pre-made, MIT-licensed skills for commit messages, code review, meeting minutes, technical proofreading, and structured research. The underlying structure of skills is stable, allowing users to customize the rules for their specific workflows.