SKILL.md Specification

Overview

SKILL.md is the standard file format for defining AI agent skills in skillshub. It is a markdown file with YAML frontmatter. The frontmatter declares metadata about the skill and the markdown body contains the actual instructions and prompts that get loaded by the AI agent at runtime.

Every skill directory must contain exactly one SKILL.md file at its root.

Frontmatter Fields

The frontmatter is a YAML block delimited by --- at the top of the file.

Required Fields

`name`

The unique identifier for the skill within its tap.

name: commit-helper

Type: string

Optional Fields

`description`

A short, single-line description of what the skill does. Displayed in search results and listings.

description: Generates conventional commit messages from staged changes

Type: string

`allowed-tools`

Tools the agent is allowed to use when executing this skill. Can be specified as a comma-separated string or a YAML array.

# Comma-separated string
allowed-tools: Tool1, Tool2, Tool3

# Or YAML array
allowed-tools:
  - Tool1
  - Tool2
  - Tool3

Type: string or list[string]

`license`

The license for the skill, using an SPDX identifier.

license: MIT

Type: string
Common values: MIT, Apache-2.0, GPL-3.0-only, BSD-2-Clause

`metadata`

A nested block for additional metadata fields.

metadata:
  author: my-org
  version: "1.0"

`metadata.author`

The skill author’s name or organization.

metadata:
  author: "@janedoe"

Type: string

`metadata.version`

A semantic version string for the skill.

metadata:
  version: "1.0"

Type: string

The license, metadata.author, and metadata.version fields are displayed by skillshub info when present.

Body Content

The markdown body below the frontmatter is the skill itself. This is the content that gets loaded into the AI agent as instructions, context, or prompts. Anything you write in the body is what the agent will see and follow.

Structure

The body is freeform markdown. You can use any standard markdown syntax including headings, lists, code blocks, tables, and emphasis. A common pattern is to structure the body with:

Instructions — what the agent should do
Rules or constraints — guardrails for behavior
Examples — sample inputs and expected outputs
Reference — schemas, APIs, or context the agent needs

---
name: example-skill
description: Example of body structure
---

## Instructions

You are a code review assistant. When the user asks you to review code, follow these steps:

1. Read through the entire diff
2. Identify bugs, security issues, and style problems
3. Provide actionable feedback with line references

## Rules

- Never approve code with known security vulnerabilities
- Keep feedback constructive and specific
- Limit review comments to the most impactful issues (max 10)

## Examples

### Input

A diff containing an SQL injection vulnerability.

### Expected Output

Flag the vulnerability, explain the risk, and suggest using parameterized queries.

Complete Examples

Minimal Skill

The smallest valid SKILL.md:

---
name: hello-world
description: A simple greeting skill
---

When the user says hello, respond with a friendly greeting and offer to help.

Full-Featured Skill

A comprehensive skill using all available fields:

---
name: commit-helper
description: Generates conventional commit messages from staged changes
allowed-tools: Read, Bash, Edit
license: MIT
metadata:
  author: "@janedoe"
  version: "1.4.0"
---

## Instructions

You are a commit message assistant. When the user asks you to write a commit message, analyze the staged changes and produce a message following the Conventional Commits specification.

## Format

Use this structure for every commit message:

<type>(<scope>): <short summary>

<body>

<footer>

### Types

| Type | When to use |
|------|------------|
| feat | A new feature |
| fix | A bug fix |
| docs | Documentation changes |
| style | Formatting, semicolons, etc. (no code change) |
| refactor | Code restructuring without behavior change |
| test | Adding or updating tests |
| chore | Build process, dependencies, or tooling |

## Rules

- Keep the summary under 72 characters
- Use the imperative mood ("add feature" not "added feature")
- Reference issue numbers in the footer when applicable
- If the change is breaking, add `BREAKING CHANGE:` in the footer

Best Practices

Write Clear Instructions

The body of your SKILL.md is a prompt. Write it as clearly and specifically as you would any important prompt. Avoid ambiguity and provide concrete examples of desired behavior.

Keep Skills Focused

Each skill should do one thing well. If a skill is growing too large or covering multiple concerns, consider splitting it into separate skills.

Use Examples Generously

AI agents perform better with examples. Include input/output pairs that demonstrate the expected behavior across common and edge cases.

Test Across Agents

Different agents may interpret the same instructions differently. Test your skill with each agent you intend to support.