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
  scripts/
    run.sh
  references/
    api-docs.md

Required Files

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

Optional Directories

Path	Purpose
scripts/	Executable scripts the agent can run
references/	Documentation to be loaded into context

Taps: GitHub Repos as Registries

Skills are organized into taps — GitHub repositories that act as registries. Any GitHub repository can be a tap. Just add folders with SKILL.md files anywhere in your repo — skills are automatically discovered:

my-skills-repo/
  skills/
    python-testing/
      SKILL.md
    code-review/
      SKILL.md
  advanced/
    refactoring/
      SKILL.md
  README.md

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

Adding a Tap

skillshub tap add user/my-skills-repo
skillshub install user/my-skills-repo/python-testing

The SKILL.md File

The SKILL.md file uses standard markdown with YAML frontmatter. The frontmatter holds metadata and the markdown body contains the actual skill instructions that get loaded into the AI agent.

---
name: my-skill
description: A short description of what this skill does
allowed-tools: Tool1, Tool2
license: MIT
metadata:
  author: my-org
  version: "1.0"
---

## Instructions

You are an assistant that helps with...

Required Fields

• name — The skill identifier

Optional Fields

• description — What this skill does and when to use it
• allowed-tools — Comma-separated string or YAML array of allowed tool names
• license — SPDX license identifier (e.g., MIT, Apache-2.0)
• metadata.author — Author or organization name
• metadata.version — Semantic version string (e.g., "1.0")

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

Installing from URLs and Gists

In addition to taps, you can install skills directly from GitHub URLs or Gists:

# From a GitHub repo URL
skillshub add https://github.com/user/repo/tree/main/skills/my-skill

# From a specific commit
skillshub add https://github.com/user/repo/tree/abc1234/skills/my-skill

# From a GitHub Gist
skillshub add https://gist.github.com/user/gist_id

Skills from repositories are organized as owner/repo/skill-name. Gist skills are organized as owner/gists/skill-name.

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, use the fully qualified name:

owner/repo/skill-name

Discovery and Resolution

When you run a command like skillshub install EYH0602/skillshub/code-reviewer, skillshub:

1. Looks up the specified tap (EYH0602/skillshub)
2. Finds the skill directory matching the name (code-reviewer)
3. Validates the SKILL.md file
4. Downloads and installs the skill

To see details about an installed skill:

skillshub info EYH0602/skillshub/code-reviewer

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
description: A minimal example skill that greets the user
---

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

skillshub install EYH0602/skillshub/hello-world
skillshub link