writing-your-first-agent-skill
Writing Your First Agent Skill
Most developers who write a skill for the first time end up with one of two outcomes: a tiny, focused, useful skill that they actually use, or a sprawling 2000-word SKILL.md that the LLM never loads because the description is too vague. The difference is not effort. It is understanding what the skill actually IS to the LLM at routing time, and what the spec lets you say.
This course is for developers who can write code but have not yet authored a skill, or have written one and want to understand WHY some skills get picked up reliably by the agent and others sit unused. Six chapters. Concrete examples. The skill you produce can be a personal skill you keep locally, a skill you share with your team, or a contribution to a public catalog. The mechanics are the same in all three cases.
Course Overview
| Chapter | What you walk away with |
|---|---|
| 1. What is a skill, really? | The mental model: skill vs MCP vs system prompt vs CLI, and when each fits |
| 2. Anatomy of a great SKILL.md | The frontmatter fields and their limits, the description as routing input, and the "Use when / Do NOT use for" pattern |
| 3. Extending the format (optional) | When you need more than the spec offers: catalog metadata and the sidecar pattern |
| 4. references/ vs scripts/ | When to use each, with worked examples |
| 5. Sharing your skill | Four scenarios: personal, team, internal catalog, public catalog |
| 6. The 10-minute pre-share checklist | The 10 most common authoring mistakes and how to avoid them |
This course assumes you have basic familiarity with git, Markdown, and JSON. No prior experience with the skill format required.