Skill Schema

Skills are Markdown files with YAML frontmatter. This page documents the complete schema.

File Structure

A skill file follows this structure:

---
<frontmatter fields>
---

<markdown body>

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

Storage Model in Char

Char uses two skill sources:

Organization skills (DB-backed)
Stored per organization and managed through the Skills UI and API.
Built-in global skills (code-owned)
Shared across all organizations and exposed through fixed location values.

Both sources use the same SKILL.md content format documented on this page. Current built-in global skill:

skill-creator-webmcp (location: builtin://skill-creator-webmcp)

Frontmatter Fields

Required

string

required

Skill identifier.

1–64 characters
Lowercase letters, numbers, hyphens
No leading hyphen
No trailing hyphen
No consecutive hyphens
Unicode allowed (NFKC normalized)

string

required

When the skill should be used.

1–1024 characters

Optional

string

License identifier (e.g., MIT, Apache-2.0).

string

Runtime requirements or environment notes.

Maximum 500 characters

string

Space-delimited list of tool names.

allowed-tools: "search_orders process_refund"

object

Arbitrary key-value pairs.

metadata:
  author: support-team
  version: "1.0"

Name Validation

Input	Valid	Reason
`customer-support`	Yes
`order-lookup`	Yes
`销售分析`	Yes	Unicode allowed
`Customer-Support`	No	Uppercase
`-customer-support`	No	Leading hyphen
`customer-support-`	No	Trailing hyphen
`customer--support`	No	Consecutive 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

Code	Message	Cause
`VALIDATION_ERROR`	`name is required`	Missing name field
`VALIDATION_ERROR`	`name must be lowercase`	Uppercase characters in name
`VALIDATION_ERROR`	`invalid name format`	Hyphenation rules violated
`VALIDATION_ERROR`	`description is required`	Missing description field
`VALIDATION_ERROR`	`description exceeds 1024 characters`	Description too long
`VALIDATION_ERROR`	`compatibility exceeds 500 characters`	Compatibility too long

Token Estimates

Content	Typical Range
Metadata only	50–100 tokens
Full skill	500–5000 tokens

​File Structure

​Storage Model in Char

​Frontmatter Fields

​Required

​Optional

​Name Validation

​Body

​Example

​API

​List Skills

​Get Skill

​Create Skill

​Update Skill

​Delete Skill

​Validation Errors

​Token Estimates

File Structure

Storage Model in Char

Frontmatter Fields

Required

Optional

Name Validation

Body

Example

API

List Skills

Get Skill

Create Skill

Update Skill

Delete Skill

Validation Errors

Token Estimates