Skills

A skill packages a reusable capability as one directory. Its SKILL.md carries YAML frontmatter (a name and a description that is the trigger surface), a markdown body that is the operator manual, and optional scripts/, references/, workflows/, and widget/. There is no compile step and no registry to edit: drop the folder under .claude/skills/ and the runtime finds it by its description.

A skill is a directory#

A skill is not a class or a plugin. It is a folder named after the skill, with SKILL.md at its root and everything the capability needs beside it. The folder name is the skill's slug. The only required file is SKILL.md; the subdirectories are added as the skill grows into them.

my-skill/                        # the skill = one directory under .claude/skills/
  SKILL.md                       # REQUIRED: frontmatter (name + description) + operator-manual body
  scripts/                       # optional: deterministic tools (stdlib, dry-run default)
    do_thing.py
  references/                    # optional: deep-dive docs the body links to
    contract.md
  workflows/                     # optional: runnable orchestration
    my-skill.workflow.js
  widget/                        # optional: self-contained index.html reading status.json
    index.html

The SKILL.md frontmatter#

The frontmatter is two required keys and one optional one. name is the slug (match it to the folder name). description is the trigger surface: the runtime reads it to decide when this skill applies, so write it keyword-rich and name the exact phrases and tasks that should fire it. allowed-tools is optional and grants least privilege as a comma list; omit it to inherit the caller's tools.

---
name: hello-world
description: The reference starter agent that sends ONE email. Use when the user
  says "hello world agent", "send one email", "send a test email", "the starter
  agent", or "how do I build an agent". Composes a short message and dispatches it
  through Resend, safe by default (a dry run unless a live send is explicitly gated).
allowed-tools: Read, Write, Bash
---

The body: safe by default first#

The body under the frontmatter is the operator manual, not a persona. Lead with the safe-by-default rule, then give a stage or command table and the exact commands an operator runs. A reader should be able to run the capability from the body alone.

The commands drive the skill's scripts/, which are standard library only and dry-run by default. The dry run composes the action and prints exactly what it would do, and touches no network:

python3 scripts/send_email.py \
  --to you@example.com \
  --subject "Hello from Jetsyn" \
  --body "Hi there. This is the Hello World skill saying hello."

Add a skill#

1. 1

   Create the folder and SKILL.md

   Make .claude/skills/<skill-name>/SKILL.md. The folder name is the skill's slug; you will repeat it as the frontmatter name.

2. 2

   Write the frontmatter

   Set name (the slug) and a keyword-rich description. The description is the trigger surface, so name the exact phrases and tasks that should fire the skill. Add allowed-tools when you want to grant least privilege.

3. 3

   Write the body

   State the safe-by-default rule first, then a stage or command table and the exact commands. This is the operator manual: what to run, the flags, and the safety rules.

4. 4

   Add subdirectories only as needed

   scripts/ (standard library only, dry-run by default, run with python3), references/ for deep-dive docs, workflows/ for *.workflow.js runs, and widget/ for a self-contained index.html reading a status.json. Add each only when the skill needs it.

5. 5

   Drop it in place

   Put the folder under .claude/skills/. There is no registration file to edit and no build step; discovery is by the frontmatter description, so the skill is live as soon as the folder exists.

Skills and employees#

A skill and an AI employee share the same SKILL.md format. An employee folder is five pieces (a definition, a SKILL.md, scripts/, a workflow, and a UI tile), and the SKILL.md is the operator-manual half of that employee. A standalone skill under .claude/skills/ is the same format without the persona: a capability any employee, or the CLI, can pick up.

So there are two ways to ship a capability. Co-locate the SKILL.md in an employee folder to make it that one employee's operator manual, or keep the skill standalone under .claude/skills/ to share it across the workspace. A fully grown standalone skill can be a whole engine: a multi-stage pipeline.py, pluggable adapters under scripts/, a *.workflow.js to run it, and a status.json that drives its widget/, all dry-run by default.

Where to go next#