Make Skill

How to create an Agent Skill that other agents (and humans) can discover and use.

When to Use

• You've built something useful and want to share it
• You want to package a repeatable workflow
• You're teaching an agent how to do something specific

Quick Start

Using Scripts (Recommended)

# 1. First time only: create your skills repo
python scripts/init.py my-skills --public

# 2. Create a new skill inside your repo
python scripts/create.py my-skill-name --output ./my-skills/ --author "You"

# 3. Edit SKILL.md and add your code to scripts/

# 4. Publish (commits and pushes to your repo)
python scripts/publish.py ./my-skills/my-skill-name

Manual Setup

1. Copy

   references/template/

   to your new skill folder
2. Edit the SKILL.md frontmatter (name, description)
3. Replace the example script with your code
4. Push to GitHub with topic

   agentskills

Done. Your skill is now discoverable.

The Format

A skill is a folder:

my-skill/
  SKILL.md          # Required: frontmatter + instructions
  scripts/          # Optional: executable code
  references/       # Optional: additional documentation
  assets/           # Optional: templates, data files

SKILL.md Structure

---
name: my-skill
description: What it does. When to use it. Be specific.
license: MIT
metadata:
  author: you
  version: "1.0"
  parent: github.com/original/skill  # if derived from another
---

# My Skill

Instructions for the agent...

## Usage

How to run it...

## Examples

Show inputs and outputs...

Required Fields

name

description

Optional Fields

license

metadata

compatibility

Writing Good Instructions

The body of SKILL.md is what agents read. Make it clear:

Do:

• Start with when to use this skill
• Give concrete usage examples
• Show expected inputs and outputs
• List requirements and dependencies
• Handle edge cases

Don't:

• Assume context the agent won't have
• Write walls of text (keep it scannable)
• Bury the important stuff

Making It Discoverable

Option A: GitHub Topic

Add topic

agentskills

Option B: Monorepo

Keep multiple skills in one repo:

my-tools/
  skill-one/
    SKILL.md
  skill-two/
    SKILL.md

Tag the repo with

agentskills

Option C: Local Only

Keep it in

~/skills/

Option D: Anywhere With a URL

Gist, pastebin, raw file host. As long as it's fetchable.

Tracking Lineage

If your skill improves or derives from another:

metadata:
  parent: github.com/user/original-skill
  parent-hash: abc123

Optional. Honor system. Helps the ecosystem.

GitHub Token Setup

The scripts require a GitHub Personal Access Token to create repos, push code, and add topics.

Creating Your Token

1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click "Generate new token (classic)"
3. Give it a name (e.g., "agent-skills")
4. Select the

   repo

   scope (full control of private repositories)
5. Generate and copy the token

Storing Your Token

Create a

.env

GITHUB_TOKEN=ghp_xxxxxxxxxxxx

Or set it as an environment variable:

GITHUB_TOKEN

GH_TOKEN

Important: The

repo

• Create repositories (init.py)
• Push code (publish.py)
• Add the

  agentskills

  topic (makes your skills discoverable)

Scripts

init.py

Initialize a skills monorepo (first time only):

python scripts/init.py my-skills              # Private repo
python scripts/init.py my-skills --public     # Public repo

Creates a GitHub repo with

agentskills

create.py

Create a skill from the template:

python scripts/create.py my-skill --output ./my-skills/
python scripts/create.py my-skill --author "You" --description "Does X" -o ./my-skills/

publish.py

Commit and push a skill to your repo:

python scripts/publish.py ./my-skills/my-skill
python scripts/publish.py ./my-skills/my-skill --message "Update skill"

Commits the skill folder, adds the

agentskills

Reference

See

references/format.md

See

references/template/