Skip to content
skillshub

SKILL.md Specification

Overview

Section titled “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 (name, version, supported agents, etc.) 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

Section titled “Frontmatter Fields”

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

Required Fields

Section titled “Required Fields”

name

Section titled “name”

The unique identifier for the skill within its tap. Must be lowercase alphanumeric with hyphens.

name: commit-helper
  • Type: string
  • Pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$
  • Must be between 2 and 64 characters

version

Section titled “version”

The version of the skill, following Semantic Versioning.

version: 1.2.0
  • Type: string
  • Format: MAJOR.MINOR.PATCH (e.g., 1.0.0, 0.3.1)
  • Pre-release labels are supported (e.g., 1.0.0-beta.1)

description

Section titled “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
  • Maximum length: 160 characters

Optional Fields

Section titled “Optional Fields”

author

Section titled “author”

The skill author’s name or GitHub handle.

author: "@janedoe"
  • Type: string

license

Section titled “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

agents

Section titled “agents”

A list of AI agents this skill is compatible with. When omitted, the skill is assumed to be agent-agnostic.

agents:
  - claude
  - cursor
  - aider
  • Type: list[string]
  • Valid values: claude, codex, aider, cursor, continue, opencode, trae

tags

Section titled “tags”

A list of tags for search and discovery. Tags help users find skills by topic or category.

tags:
  - git
  - commits
  - productivity
  • Type: list[string]
  • Each tag must be lowercase alphanumeric with hyphens
  • Maximum of 10 tags per skill

dependencies

Section titled “dependencies”

A list of other skills that this skill depends on. Dependencies are installed automatically.

dependencies:
  - git-utils
  - text-formatter
  • Type: list[string]
  • Each entry is a skill name (or tap/skill-name for non-default taps)
  • Circular dependencies are not allowed

Body Content

Section titled “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

Section titled “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:

  1. Instructions — what the agent should do
  2. Rules or constraints — guardrails for behavior
  3. Examples — sample inputs and expected outputs
  4. Reference — schemas, APIs, or context the agent needs
---
name: example-skill
version: 1.0.0
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

Section titled “Complete Examples”

Minimal Skill

Section titled “Minimal Skill”

The smallest valid SKILL.md:

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


When the user says hello, respond with a friendly greeting and offer to help.
Section titled “Full-Featured Skill”

A comprehensive skill using all available fields:

---
name: commit-helper
version: 1.4.0
description: Generates conventional commit messages from staged changes
author: "@janedoe"
license: MIT
agents:
  - claude
  - cursor
  - codex
tags:
  - git
  - commits
  - conventional-commits
  - productivity
dependencies:
  - git-utils
---


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

():

```

Types

Section titled “Types”
TypeWhen to use
featA new feature
fixA bug fix
docsDocumentation changes
styleFormatting, semicolons, etc. (no code change)
refactorCode restructuring without behavior change
testAdding or updating tests
choreBuild process, dependencies, or tooling

Rules

Section titled “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

Examples

Section titled “Examples”

Input

Section titled “Input”

A diff that adds a new /users endpoint to an Express app.

Output

Section titled “Output”
feat(api): add GET /users endpoint


Implement a new REST endpoint that returns a paginated list of users.
Includes query parameters for filtering by role and sorting by name.


Closes #142
## 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, split it into separate skills and use `dependencies` to compose them.


### Specify Agent Compatibility


Always include the `agents` field if your skill relies on features specific to certain agents. Omit it only if the skill is truly agent-agnostic.


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


If you list multiple agents in the `agents` field, test the skill with each one. Different agents may interpret the same instructions differently.


## Versioning Guidelines


Follow [Semantic Versioning](https://semver.org/) for all skill versions:


- **MAJOR** (`2.0.0`): Breaking changes to the skill's behavior or interface. For example, the skill now produces output in a fundamentally different format, or it drops support for an agent.
- **MINOR** (`1.1.0`): New functionality added in a backward-compatible way. For example, the skill now handles an additional edge case or supports a new agent.
- **PATCH** (`1.0.1`): Backward-compatible fixes. For example, a typo correction in the instructions or a minor improvement to an example.


Start new skills at `0.1.0`. Use the `0.x.x` range while the skill is experimental and its behavior may still change significantly. Promote to `1.0.0` when the skill is stable and ready for broad use.


```bash
# Check the current version of an installed skill
skillshub info commit-helper


# Update a skill to its latest version
skillshub update commit-helper