TL;DR: The Agent Skills validator tells you a SKILL.md is well formed. It can't tell you whether an agent will pick the skill at the right moment, run it safely, and know when to stop. This tutorial takes one skill from valid to useful in six steps, by hand, using only the Agent Skills specification and its reference validator.

New here? Agent Skills is an open format for giving AI agents new abilities: a folder with a SKILL.md file (YAML frontmatter, then Markdown instructions), plus any scripts or references it needs. It's an AAIF project, and many agent products read it.

The skill we'll fix

Here's a complete, valid skill:

--- name : release-notes description : Helps with releases. ---

Write release notes.

Enter fullscreen mode

Exit fullscreen mode

Check it with skills-ref , the specification's reference validator.…