---
type: reference
title: SKILL.md Format
description: The required frontmatter fields, optional fields, internal skills, and structure for SKILL.md files.
tags:
  - skills
  - SKILL.md
  - format
  - unverified
verified: 2026-08-28

# SKILL.md Format

Skills are directories containing a `SKILL.md` file with YAML frontmatter.

## Basic Structure

```markdown
---
name: my-skill
description: What this skill does and when to use it
---

# My Skill

Instructions for the agent to follow when this skill is activated.

## When to Use

Describe the scenarios where this skill is used.

## Steps

1. First, do this
2. Then, do that
```

## Required Frontmatter Fields

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Unique identifier (lowercase, hyphens allowed) |
| `description` | string | Brief explanation of what the skill does |

## Optional Frontmatter Fields

| Field | Type | Description |
|-------|------|-------------|
| `metadata.internal` | boolean | Set to `true` to hide the skill from normal discovery. Requires `INSTALL_INTERNAL_SKILLS=1` |
| `license` | string | License name or reference to bundled file |
| `compatibility` | string | Environment requirements (max 500 chars) |
| `metadata` | object | Arbitrary key-value mapping |
| `allowed-tools` | string | Space-delimited list of pre-approved tools (experimental) |
| `disable-model-invocation` | boolean | When `true`, skill is hidden from system prompt. Users must use `/skill:name` explicitly |

## Internal Skills Example

```markdown
---
name: my-internal-skill
description: An internal skill not shown by default
metadata:
  internal: true
---
```

## Related

* [Skill Discovery](/tools/vercel-labs-skills/skill-discovery.md) — How skills are discovered in repos
* [Commands](/tools/vercel-labs-skills/commands.md) — `skills init` to create new skills