Creating Agent Skills

Agent Skills are a portable, open format for giving AI agents specialized knowledge and capabilities.

Directory Structure

A skill is a folder containing at minimum a SKILL.md file:

skill-name/
├── SKILL.md          # Required: instructions + metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: detailed documentation
└── assets/           # Optional: templates, resources

Skill Locations

Project skills take precedence over global skills with the same name.

Note: OpenCode also supports ~/.config/opencode/skills/ and .opencode/skills/ paths.

SKILL.md Format

Every skill must have YAML frontmatter followed by Markdown content:

---
name: skill-name
description: What this skill does and when to use it.
license: MIT                        # Optional
compatibility: Claude Code          # Optional
metadata:                           # Optional
  author: example
  version: "1.0"
---

# Markdown instructions here

Required Fields

name

• •1-64 characters
• •Lowercase alphanumeric and hyphens only (a-z, 0-9, -)
• •Must not start or end with -
• •Must not contain consecutive hyphens (--)
• •Must match the parent directory name

Valid: pdf-processing, code-review, git-workflow Invalid: PDF-Processing, -pdf, pdf--processing

description

• •1-1024 characters
• •Describe both what the skill does and when to use it
• •Include keywords that help agents identify relevant tasks

Good:

description: Extract text and tables from PDF files, fill PDF forms, and merge multiple PDFs. Use when working with PDF documents.

Bad:

description: Helps with PDFs.

Optional Fields

Body Content Guidelines

The Markdown body contains instructions for the agent. Recommended sections:

1. •Overview - What this skill accomplishes
2. •When to use - Specific triggers or scenarios
3. •Step-by-step instructions - How to perform the task
4. •Examples - Input/output samples
5. •Edge cases - Common issues and how to handle them

Length Guidelines

• •Keep main SKILL.md under 500 lines (~5000 tokens)
• •Move detailed reference material to references/ directory
• •Agents load skills on-demand, so smaller = faster activation

Progressive Disclosure

Skills are designed for efficient context usage:

1. •Startup: Only name + description loaded (~100 tokens per skill)
2. •Activation: Full SKILL.md loaded when skill is selected
3. •Execution: Scripts/references loaded only when needed

File References

When referencing other files, use relative paths from the skill root:

See [detailed reference](references/REFERENCE.md) for more.

Run the helper script:
scripts/helper.py

Creating a New Skill

Use the skills CLI to scaffold new skills:

Global Skill (available in all projects)

cd ~/.agents/skills
npx skills init my-skill
# Edit my-skill/SKILL.md with your instructions

Project Skill (available in current project only)

cd /path/to/project
mkdir -p .claude/skills
cd .claude/skills
npx skills init my-skill
# Edit my-skill/SKILL.md with your instructions
# Commit to version control

Verify the Skill

After creating, the skill should appear in the agent's available skills list. Test by asking the agent to use it.

Example: Complete Skill

---
name: conventional-commits
description: Create conventional commit messages following the Conventional Commits specification. Use when committing code or asked about commit message format.
license: MIT
metadata:
  author: mjp
  version: "1.0"
---

# Conventional Commits

## Format

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

## Types
| Type | When to use |
|------|-------------|
| feat | New feature |
| fix | Bug fix |
| docs | Documentation only |
| style | Formatting, no code change |
| refactor | Code change that neither fixes nor adds |
| test | Adding or updating tests |
| chore | Maintenance tasks |

## Rules
- Use present tense ("Add feature" not "Added feature")
- Keep subject line under 72 characters
- Capitalize the description
- No period at the end of subject line

## Examples
- `feat(auth): add OAuth2 login support`
- `fix(api): handle null response from server`
- `docs: update installation instructions`

Managing Skills with the CLI

Installing Skills from Repositories

# Install globally (user-level)
npx skills add owner/repo@skill-name -g -y

# Install to current project
npx skills add owner/repo@skill-name -y

# Search for skills
npx skills find <query>

Updating Skills

# Check for updates
npx skills check

# Update all installed skills
npx skills update

Removing Skills

# Remove the skill directory
rm -rf ~/.agents/skills/skill-name        # global
rm -rf .claude/skills/skill-name          # project

# Regenerate lock file
npx skills generate-lock

Lock File

The .skill-lock.json file tracks installed skills for updates:

• •Located in ~/.agents/ for global skills
• •Located in .claude/ for project skills
• •Only tracks skills installed via npx skills add
• •Custom skills created with npx skills init are not tracked

Validation

Use the official reference library to validate skills:

npx skills-ref validate ./my-skill

Resources

• •Skills Directory: https://skills.sh
• •Specification: https://agentskills.io/specification
• •Example skills: https://github.com/anthropics/skills
• •Reference library: https://github.com/agentskills/agentskills/tree/main/skills-ref