Skill Format

The SKILL.md format specification for creating agent-readable documentation.

Overview

Skills are documented using SKILL.md files — a markdown-based format with YAML frontmatter that both humans and AI agents can read and understand. This format is inspired by skill systems used by AI coding agents like Claude Code.

The format is intentionally simple: frontmatter for metadata, markdown for content. This makes skills easy to write, version control, and distribute.

File Structure

A minimal skill contains just one file:

SKILL.md

---
name: my-skill
description: What this skill does
---

# My Skill

Instructions for using this skill...

More complex skills can include additional files:

File Structure

my-skill/
├── SKILL.md          # Main documentation
├── component.tsx     # Component code
├── styles.css        # Styling
└── example.tsx       # Usage example

Frontmatter Fields

The frontmatter section (between the triple dashes) contains metadata about the skill:

Required Fields

name — The skill name (kebab-case recommended)
description — A brief description of what the skill does

Optional Fields

user-invocable — Whether users can directly invoke this skill (default: true)
allowed-tools — List of tools this skill can use
version — Semantic version of the skill
author — Author name or username
license — License type (MIT, Apache-2.0, etc.)

Example Frontmatter

SKILL.md

---
name: button-component
description: Guidelines for creating accessible, consistent buttons
user-invocable: true
allowed-tools: Bash(npm install *), Edit, Write
version: 1.0.0
author: johndoe
license: MIT
---

Content Sections

The markdown content after the frontmatter should include these standard sections:

1. Title and Description

SKILL.md

# Button Component

Guidelines for creating consistent, accessible buttons across your application.

2. Usage

Explain how users (or AI agents) should invoke this skill:

SKILL.md

## Usage

When creating buttons, tell the AI:

> "Use the button-component skill to create a primary submit button"

The skill will ensure:
- Proper semantic HTML (<button> not <div>)
- Accessible focus states
- Consistent sizing and spacing
- Theme-aware colors

3. Examples

Provide concrete examples showing the skill in action:

SKILL.md

## Examples

### Primary Button

```tsx
<Button variant="primary" size="md">
  Submit
</Button>
```

### With Icon

```tsx
<Button variant="secondary" size="sm">
  <DownloadIcon />
  Download
</Button>
```

4. API Reference

Document props, options, or configuration:

SKILL.md

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| variant | 'primary' \| 'secondary' \| 'ghost' | 'primary' | Visual style |
| size | 'sm' \| 'md' \| 'lg' | 'md' | Button size |
| disabled | boolean | false | Disabled state |

5. Best Practices

Include guidelines for using the skill correctly:

SKILL.md

## Best Practices

- Always use `type="button"` unless it's a submit
- Include loading states for async actions
- Ensure 44×44dp minimum touch target
- Don't override colors directly — use CSS variables

Multi-File Skills

For complex skills with multiple components or files, organize them in a logical structure. The SKILL.md should serve as the entry point and reference other files as needed.

Referencing Other Files

SKILL.md

# Form System

This skill includes multiple components for building forms.

## Files

- `form.tsx` — Main form component with validation
- `field.tsx` — Individual field wrapper
- `validation.ts` — Validation utilities

See the individual files for implementation details.

Design Tokens

If your skill defines design tokens (colors, spacing, typography), document them in a clear, referenceable format:

SKILL.md

## Design Tokens

### Colors

| Token | Value | Usage |
|-------|-------|-------|
| --color-primary | #3b82f6 | Primary actions |
| --color-secondary | #64748b | Secondary actions |

### Spacing

| Token | Value |
|-------|-------|
| --space-1 | 0.25rem (4px) |
| --space-2 | 0.5rem (8px) |
| --space-3 | 0.75rem (12px) |
| --space-4 | 1rem (16px) |

AI-Optimized Writing Tips

Be Explicit

Don't assume the AI will infer what you mean. Be explicit about:

What problem the skill solves
When to use it vs. alternatives
What files to create/modify
What dependencies are needed

Use Imperative Voice

Write instructions as commands:

SKILL.md

## Usage

1. Import the Button component from @/components/ui/button
2. Use the 'variant' prop to set the visual style
3. Always include an aria-label for icon-only buttons

Provide Context

Explain why patterns are used, not just what to do:

SKILL.md

## Why These Patterns?

Buttons use CSS Grid for layout instead of Flexbox because:
- Grid handles misaligned content better
- Easier to implement the loading state spinner
- Consistent alignment regardless of content length

Validation

To validate your SKILL.md format:

Ensure frontmatter is valid YAML
Check that name and description fields exist
Verify markdown renders correctly
Test the skill with an AI agent

Examples

Here are some real-world skill examples from the TokenUI registry:

Simple Component Skill

Example: Button Skill

---
name: button
description: Accessible button component with variants
---

# Button Component

Create consistent, accessible buttons.

## Usage

"Use the button skill to create a primary CTA button"

## Variants

- primary: Main actions, solid background
- secondary: Alternative actions, outlined
- ghost: Low emphasis, no background

Complex System Skill

Example: Design System Skill

---
name: design-system
description: Complete design system for React applications
---

# Design System

Comprehensive tokens and components.

## Tokens

See tokens.css for:
- Colors (primary, secondary, semantic)
- Typography (font, sizes, weights)
- Spacing (4px base grid)
- Shadows and elevations

## Components

- Button — All variants documented
- Card — With proper elevation
- Input — With validation states

## Usage

Reference specific component:
"Use the button from design-system skill"