Authoring skills

A skill is a folder you can read, version, and share. Authoring one is mostly writing clear instructions — there’s no build step and no runtime to configure.

Folder structure

Every skill is a folder whose only required file is SKILL.md. Alongside it you can bundle helper scripts and reference material:

apa-citations/
  SKILL.md          # required — frontmatter + instructions
  scripts/
    check.js        # optional — a runnable helper
  reference/
    examples.md     # optional — material the skill can draw on

The SKILL.md frontmatter

SKILL.md opens with YAML frontmatter, then the instructions in Markdown. The name identifies the skill; the description is what the AI reads to decide when the skill applies, so make it specific about when to use it; and allowed-tools scopes which tools the skill may use while it runs.

---
name: apa-citations
description: >-
  Format references and in-text citations in APA 7th edition. Use when the
  user asks for APA style, a reference list, or to fix citation formatting.
allowed-tools: ["editor.read", "editor.write"]
---

# APA citations

When asked to format citations:

1. Put the reference list in alphabetical order by first author.
2. Use the author-date form for in-text citations, e.g. (Smith, 2021).
3. Hanging-indent each reference entry.

Run scripts/check.js to validate a finished reference list.

Bundled scripts & files

A skill can carry runnable scripts and reference files in its folder. The instructions tell the AI when to run a script or consult a file, so a skill brings both the know-how and the tools with it. Scripts run in the same secure, permissioned environment as any other agent code — see tools & compute.

Creating & editing a skill

You can author a skill three ways:

1. By hand

   Create the folder and SKILL.md yourself and drop it in with your other skills.

2. With the AI

   Ask the AI to create one for you with the /createskill command, or in chat — it scaffolds the folder, frontmatter, and a first draft of the instructions.

3. From the Skills Manager

   Use the Skills Manager to create, edit, or delete skills and toggle them on and off.

Linting, export & import

A built-in linter checks a skill for common problems — a missing description, an undeclared tool — before you rely on it. To move a skill between machines or hand it to a colleague, export it as a .skill.json bundle and import it on the other side. To share it with everyone, publish it to the marketplace.