> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usechar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Skill Schema

> SKILL.md format specification with YAML frontmatter fields, name validation rules, and API endpoints

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:

1. **Organization skills (DB-backed)**\
   Stored per organization and managed through the Skills UI and API.
2. **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

<ParamField path="name" type="string" required>
  Skill identifier.

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

<ParamField path="description" type="string" required>
  When the skill should be used.

  * 1–1024 characters
</ParamField>

### Optional

<ParamField path="license" type="string">
  License identifier (e.g., `MIT`, `Apache-2.0`).
</ParamField>

<ParamField path="compatibility" type="string">
  Runtime requirements or environment notes.

  * Maximum 500 characters
</ParamField>

<ParamField path="allowed-tools" type="string">
  Space-delimited list of tool names.

  ```yaml theme={null}
  allowed-tools: "search_orders process_refund"
  ```
</ParamField>

<ParamField path="metadata" type="object">
  Arbitrary key-value pairs.

  ```yaml theme={null}
  metadata:
    author: support-team
    version: "1.0"
  ```
</ParamField>

## 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

```markdown theme={null}
---
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 |

<Snippet file="support-cta.mdx" />