What is a Skill?

A skill is a self-contained bundle of instructions (and optional assets) that an AI agent can discover and follow.

Structure

my-skill/
├── SKILL.md          # required — instructions + frontmatter
├── assets/           # optional — images, templates, reference files
└── scripts/          # optional — helper scripts the agent can run

SKILL.md anatomy

---
name: my-skill
description: A short, specific description the agent uses to decide when to apply this skill.
tags: [reporting, finance]
---

# My Skill

Step-by-step instructions the agent follows when the skill is invoked.

1. Do this first
2. Then this
3. Finally this

The description is the most important field — agents read it to decide whether the skill is relevant to a user's request. Be specific about what the skill does and when to use it.

Other frontmatter fields

The scaffold from sherpi skills create includes a commented reference block listing every supported field, including:

• tags — categories used to filter the catalog
• when_to_use — extra trigger guidance for the agent

Read the reference block in the scaffolded SKILL.md for the full list.

Why skills and not plugins?

Skills are:

• Plain text — authored in markdown, not code
• Composable — the agent can combine multiple skills in one response
• Editor-agnostic — same skill works in Claude Code, Cursor, Codex
• Reviewable — a PR-style review flow for your team
• Versioned — roll forward and back safely

Unlike editor-specific plugins, skills live in your org's library and flow into whichever editor your team is using.