← Back to articlesSkills and MCP

What is SKILL.md, and what belongs in a skill folder?

In the Agent Skills format, SKILL.md contains metadata and instructions, with optional scripts, references and assets alongside it.

The short answer

Start with text instructions before adding executable code.

Try it in three steps

  • Create a practice skill folder.
  • Follow the format for name, description and procedure.
  • Check that referenced files exist.

A practice prompt

Before you start

Create a note-sorter folder and save a plain-text SKILL.md inside it, not SKILL.md.txt. Put the following content in the file; do not import or run it here.

Practice material (fictional)

---
name: note-sorter
description: Group short notes by topic.
---
# Organize notes
Group supplied notes by topic and separate unknowns.

Replace placeholders in the prompt with this material, or append the material if there are no placeholders. Reading time excludes doing the exercise.

Draft a text-only skill for meeting notes with inputs, outputs and handling of unknown owners. Include no scripts or external sending.

What to look for (not a recorded test result)

Lines one and four are ---. The name matches the folder, the description is nonempty and the body follows the second ---. Correct format does not prove client loading.

If it goes wrong

If recognition fails, check client compatibility and the format rather than repeatedly renaming files.

Check your result

Another reader understands the task and all resource paths resolve.

References and scope

The links below support the concepts or product navigation. The steps and exercises are our teaching suggestions, not official certification or measured customer outcomes. Product interfaces and availability may change. References checked on 2026-10-17.

Start with one task

Describe the current process and its slowest step. The initial conversation is free.

Let’s talk ↗
Need help? See small-scale implementation services ↗

Keep reading