$ skilldirectory
— zsh — registry.skilldirectory.dev
skill library blog

home / what is a SKILL.md file?

what is a SKILL.md file?

the short version

SKILL.md is a plain text file with two parts: a small block of front matter at the top, then instructions written in Markdown. The front matter tells the agent what the skill is and when to use it. The instructions tell the agent how to do the job once it has decided the skill applies.

the front matter

At minimum the front matter has a name and a description. The name is a short identifier. The description is the part that matters most, because an agent reads the descriptions of all your installed skills and uses them to decide which one fits the task in front of it. Good descriptions say what the skill does and name the situations that should trigger it. Vague descriptions are the most common reason a skill never gets used.

the instructions

The body is ordinary Markdown: steps to follow, rules to respect, examples of good output and sometimes a list of mistakes to avoid. Well-written skills say when to use them and when not to, define what finished work looks like, and stay short enough that the agent can hold them in mind. Long skills usually split detail into extra files and point to them from SKILL.md.

supporting files

A skill folder can hold more than SKILL.md: scripts the agent can run, reference documents it can read, templates and sample data. The agent opens these only when the instructions send it there. Scripts deserve extra care, because they can do anything your agent is allowed to do. The safety checklist covers what to look for.

how to read one before you install it

  • Read the description. Does it match the job you actually have?
  • Skim the headings to see what the skill covers and in what order.
  • Look for a prerequisites or setup section, which tells you what else must be in place.
  • Open any scripts in the folder and read them, or ask your agent to explain them.
  • Check the license and when the repository was last updated.

Every skill page on SkillDirectory shows an outline of the original file's sections and links to the full text in its repository.