Writing a skill

A skill is a SKILL.md file: YAML frontmatter plus Markdown instructions. Upload a single file as-is, or a zip with SKILL.md at its root. To upload it, see Publishing skills.

Example

SKILL.md

---
name: Expense report review
description: Review a submitted expense report against the T&E policy and either approve it or send it back with the specific line items that need receipts. Use when someone asks to review, approve, or check an expense report.
---
# Expense report review
## Steps
1. Pull the report with `expensify__get_report`. Note the submitter and total.
2. Check every line item over $75 for an attached receipt.
3. Check the report against the T&E limits in `references/te-policy.md`.
4. Approve if every line passes. Otherwise reject with the failing line items named individually.
## Rules
- Never approve a report you submitted yourself. Hand those to the submitter's manager.
- A missing receipt is a send-back, not a judgment call.

Frontmatter

Key	Required	What it does
`name`	Yes	Display name. The slug is derived from it.
`description`	Yes	Returned by `list_skills`. Agents match on name and description only, so use the words people use for the task.
`referenced_connectors`	No	YAML list of Connector slugs, such as `["expensify", "slack"]`. Shown on the card. Grants no access.

Bundled files

Put long reference material in separate files and reference them by relative path (references/te-policy.md). Agents fetch a bundled file only when they need it.

expense-report-review.zip
├── SKILL.md
├── references/
│   └── te-policy.md
└── examples/
    └── rejection-message.md

Don’t include credentials: everyone the skill reaches can read it.

Limits

Limit	Value
Upload size, compressed	10 MB
Bundle size, uncompressed	10 MB
Any single file	2 MB
File count	100
`SKILL.md` length	20,000 characters

SKILL.md must be UTF-8. Symlinks and paths that escape the bundle are rejected.

Upload errors and fixes

Error	Fix
`Bundle must contain a SKILL.md at its root`	Re-zip from inside the skill directory
`SKILL.md must start with YAML frontmatter delimited by '---'`	Make the opening `---` the first line
`SKILL.md frontmatter is not valid YAML`	Usually an unquoted colon in a value. Quote it.
`SKILL.md frontmatter is missing a non-empty 'name'`	Set a non-empty string `name` and `description`
`frontmatter 'referenced_connectors' must be a list of slugs`	Use a YAML list, not a comma-separated string
`The 'merge-' slug prefix is reserved`	Rename the skill so its slug doesn’t start with `merge-`
`Symlinks are not allowed in a skill bundle`	Copy the real file in instead