Skip to main content
Skills are Markdown files with YAML frontmatter. This page documents the complete schema.

​
File Structure

---
<frontmatter fields>
---

<markdown body>
The frontmatter is delimited by --- on its own line. Everything after the closing delimiter is the body.

​
Frontmatter Fields

​
Required

​
name
string
required
Skill identifier.
  • 1–64 characters
  • Lowercase letters, numbers, hyphens
  • No leading hyphen
  • No trailing hyphen
  • No consecutive hyphens
  • Unicode allowed (NFKC normalized)
​
description
string
required
When the skill should be used.
  • 1–1024 characters

​
Optional

​
license
string
License identifier (e.g., MIT, Apache-2.0).
​
compatibility
string
Runtime requirements or environment notes.
  • Maximum 500 characters
​
allowed-tools
string
Space-delimited list of tool names.
allowed-tools: "search_orders process_refund"
​
metadata
object
Arbitrary key-value pairs.
metadata:
  author: support-team
  version: "1.0"

​
Name Validation

InputValidReason
customer-supportYes
order-lookupYes
销售分析YesUnicode allowed
Customer-SupportNoUppercase
-customer-supportNoLeading hyphen
customer-support-NoTrailing hyphen
customer--supportNoConsecutive hyphens

​
Body

The body is Markdown. No schema constraints apply. Content appears verbatim in the agent’s context when the skill is activated.

​
Example

---
name: refund-processor
description: Handle refund requests for orders within the return window
license: MIT
compatibility: Requires order_management tools
metadata:
  owner: billing
  version: "1.2"
---

# Refund Processor

Process refund requests according to policy.

## Eligibility

- Order within 30-day window
- Item unused and in original packaging
- Customer provides order ID

## Process

1. Verify eligibility
2. Confirm refund amount
3. Process refund
4. Send confirmation

## Escalation

Transfer to human support for:
- Requests outside window
- Amounts over $500
- Disputed charges

​
API

​
List Skills

POST /organization-skills/list
Returns skill metadata (name, description, id). Does not include body.

​
Get Skill

GET /organization-skills/{id}
Returns full skill including body.

​
Create Skill

POST /organization-skills
Request body: { "content": "<full SKILL.md content>" }

​
Update Skill

PATCH /organization-skills/{id}
Accepts patch operations.

​
Delete Skill

DELETE /organization-skills/{id}
Archives the skill. Does not permanently delete.

​
Validation Errors

CodeMessageCause
VALIDATION_ERRORname is requiredMissing name field
VALIDATION_ERRORname must be lowercaseUppercase characters in name
VALIDATION_ERRORinvalid name formatHyphenation rules violated
VALIDATION_ERRORdescription is requiredMissing description field
VALIDATION_ERRORdescription exceeds 1024 charactersDescription too long
VALIDATION_ERRORcompatibility exceeds 500 charactersCompatibility too long

​
Token Estimates

ContentTypical Range
Metadata only50–100 tokens
Full skill500–5000 tokens