SKILL.md format
The skill manifest: structure, required fields, tools, inputs, and examples.
Every Skill is defined by one file: SKILL.md. It tells the agent what the Skill does, when to use it, and how to do it. Get the manifest right and the Skill triggers reliably; get it wrong and the agent never picks it up. This page is the reference for the format.
File structure
A Skill is a directory containing a SKILL.md manifest, plus optional supporting files:
my-skill/
├── SKILL.md ← required: frontmatter + instructions
├── scripts/ ← optional: executable helpers the Skill runs
├── references/ ← optional: docs the agent loads as needed
└── assets/ ← optional: files used in the Skill's outputThe manifest itself is YAML frontmatter followed by a Markdown body:
---
name: keyword-research
description: Discover high-intent keywords and cluster them by topic. Use when the user asks to research keywords or analyze search intent.
---
# Keyword Research
Instructions for the agent go here — the actual steps to run the workflow.Required fields
Two frontmatter fields are required:
| Field | Required | Description |
|---|---|---|
name | ✓ | Short identifier for the Skill. |
description | ✓ | What the Skill does and when to use it. This is the primary trigger — the agent reads it to decide whether to run the Skill, so be specific and include the situations or phrases that should activate it. |
Put all triggering context in description, not the body. A vague description ("helps with content") rarely fires; a specific one ("use when the user asks to rewrite a blog post for social channels") fires reliably.
Optional fields
| Field | Description |
|---|---|
version | Version string, e.g. "1.0.0". |
author | Who published the Skill. |
tags | Comma-separated categories for filtering and discovery. |
allowed-tools | The tools the Skill is permitted to use, e.g. Read, Write, Edit, Bash. The Skill can't reach beyond these. |
user-invocable | Whether a person can trigger the Skill manually (vs. agent-only). |
compatibility | Required tools or dependencies the Skill needs. |
metadata | Custom key-value pairs. |
The Markdown body holds the operating instructions — keep it focused and use sections and links to keep it readable rather than dumping everything inline.
Tools and inputs
- Tools — declare what a Skill may use with
allowed-tools. Skills run inside the agent's own cloud computer, so a Skill can only use tools the agent already has. - Inputs — Skills don't take a fixed parameter signature; the agent supplies what the workflow needs from the conversation. Describe the inputs you expect (file paths, a topic, a target format) in the body so the agent knows what to gather before running.
Examples
Minimal Skill:
---
name: My Skill
description: A one-sentence summary of what this does and when to use it.
---
# My Skill
Step-by-step instructions for the agent.Fuller manifest:
---
name: blog-to-social
description: Rewrite a finished blog post into Xiaohongshu, LinkedIn, and a short-video script. Use when the user finishes a blog post and asks for social versions.
version: "1.2.0"
author: Content Ops
tags: marketing, content, repurposing
allowed-tools: Read, Write, Edit
---
# Blog to Social
1. Read the source blog post the user points to.
2. Produce a Xiaohongshu draft, a LinkedIn post, and a 30-second video script.
3. Save each to the agent Drive and link them back in the chat.A few details to know: if both skill.json and SKILL.md exist, skill.json wins. If no manifest is found, the Skill falls back to the directory name and an empty description — which usually won't trigger, so always ship a SKILL.md.