Skill Format

What Is a Skill?

A skill is a directory inside a GitHub repository that contains a SKILL.md file. The SKILL.md file defines everything about the skill: its metadata (via YAML frontmatter) and its actual content (the markdown body, which contains the instructions and prompts loaded by an AI agent).

Skills are the fundamental unit of distribution in skillshub. You can think of them as packages — each one is a self-contained piece of functionality that can be installed, linked to an agent, and shared with others.

Directory Structure

At minimum, a skill is a single SKILL.md file inside a named directory:

my-skill/
  SKILL.md

Skills can also include optional supporting assets:

my-skill/
  SKILL.md
  assets/
    schema.json
    template.hbs
  examples/
    usage.md

Required Files

File	Purpose
SKILL.md	The skill definition — metadata frontmatter plus markdown body containing the agent instructions

Optional Files

Path	Purpose
assets/	Static files referenced by the skill (schemas, templates, configs)
examples/	Example usage or sample outputs
README.md	Human-readable documentation (not loaded by agents)

Taps: GitHub Repos as Registries

Skills are organized into taps — GitHub repositories that act as registries. A tap is simply a repo containing one or more skill directories at its root:

my-tap/                    # GitHub repo: github.com/user/my-tap
  commit-helper/
    SKILL.md
  code-reviewer/
    SKILL.md
  test-writer/
    SKILL.md

The default tap is skillshub/core, which contains officially maintained skills. You can add third-party taps or create your own.

Adding a Tap

skillshub tap add github.com/user/my-tap

Once a tap is added, all skills inside it become available for installation.

The SKILL.md File

The SKILL.md file uses standard markdown with YAML frontmatter. The frontmatter holds metadata (name, version, description, supported agents, etc.) and the markdown body contains the actual skill instructions that get loaded into the AI agent.

---
name: my-skill
version: 0.1.0
description: A short description of what this skill does
agents:
  - claude
  - cursor
tags:
  - productivity
---

## Instructions

You are an assistant that helps with...

For the full specification of all frontmatter fields and body conventions, see the SKILL.md Specification.

Naming Conventions

Skill names must follow these rules:

• Lowercase alphanumeric characters and hyphens only (e.g., commit-helper, code-reviewer)
• No spaces or underscores — use hyphens as separators
• Unique within a tap — two skills in the same tap cannot share a name
• Descriptive and concise — the name should give a clear idea of what the skill does

When referencing a skill from a non-default tap, use the fully qualified name:

tap-name/skill-name

For skills in the default skillshub/core tap, the short name is sufficient:

skill-name

Discovery and Resolution

When you run a command like skillshub install commit-helper, skillshub resolves the skill using the following order:

1. Check all configured taps in priority order (default tap first, then user-added taps in the order they were added)
2. Match by name — look for a directory matching the skill name that contains a valid SKILL.md
3. Return the first match — if the same skill name exists in multiple taps, the first match wins

You can bypass resolution by using a fully qualified name:

# Install from a specific tap
skillshub install my-tap/commit-helper

To see which tap a skill would resolve to:

skillshub info commit-helper

Example: Minimal Skill

Below is the smallest valid skill — a single directory with a SKILL.md file:

hello-world/
  SKILL.md

Contents of SKILL.md:

---
name: hello-world
version: 0.1.0
description: A minimal example skill that greets the user
agents:
  - claude
---

## Instructions

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

This skill can be installed and linked to an agent immediately:

skillshub install hello-world
skillshub link hello-world --agent claude