Skip to main content

Skill Format

The structure and metadata of a skillshare skill.

When does this matter?

The SKILL.md format determines how AI CLIs discover and load your skill. The description field is especially critical — it's what the AI uses to decide when to activate your skill.

Overview​

A skill is a directory containing at least a SKILL.md file:

my-skill/
└── SKILL.md

The SKILL.md file has two parts:

  1. YAML frontmatter — Metadata
  2. Markdown body — Instructions for the AI

Basic Structure​

---
name: my-skill
description: Brief description of what this skill does
---

# My Skill

Instructions for the agent when this skill is activated.

## When to Use

Describe when this skill should be used.

## Instructions

1. First step
2. Second step
3. Additional steps as needed

Required Fields​

name​

The skill identifier. Used for:

  • Invoking the skill (e.g., /skill:my-skill)
  • Collision detection
  • Display in skill lists
name: my-skill

Rules:

  • Lowercase letters, numbers, hyphens, underscores
  • Must start with a letter or number
  • Should be unique across all skills

Examples:

name: code-review
name: pdf-tools
name: acme-frontend-ui  # Namespaced for teams

Optional Fields​

description​

Brief description shown in skill lists and search results.

description: Reviews code for bugs, style issues, and improvements

Optional Fields​

tags​

Classification tags for filtering and grouping in hub indexes. When you run skillshare hub index, tags from SKILL.md frontmatter are included in the generated skillshare-hub.json.

tags: git, workflow

Tags are also searchable — skillshare search workflow --hub ... matches skills tagged with "workflow".

targets​

Restrict which targets this skill syncs to. When omitted, the skill syncs to all targets.

Supports two placement styles — under metadata: (recommended) or at the top level:

# Recommended: under metadata
metadata:
  targets: [claude, cursor]

# Legacy: top-level (still fully supported)
targets: [claude, cursor]
Priority rule

If both are present, metadata.targets takes priority over the top-level targets. This lets you migrate gradually — adding metadata: won't conflict with a leftover top-level field.

ValueBehavior
(omitted)Syncs to all targets (default)
[claude]Syncs only to targets matching "claude"
[claude, cursor]Syncs to targets matching either name

Cross-mode matching: A skill declaring targets: [claude] also matches the project target claude, because both refer to the same AI CLI. Matching uses the target registry.

Interaction with config filters: Skill-level targets is applied after config-level include/exclude. Both must pass for a skill to be synced. See Configuration.

Example — Claude-only skill:

---
name: claude-prompts
description: Prompt patterns for Claude Code
metadata:
  targets: [claude]
---

# Claude Prompts
...

This skill will only appear in Claude Code's skills directory, even if you have Cursor, Codex, and other targets configured.

pattern​

The structural design pattern used by this skill. Generated automatically by skillshare new -P <pattern>.

pattern: reviewer

Available patterns: tool-wrapper, generator, reviewer, inversion, pipeline. See Skill Design Patterns for details on each.

category​

The use-case category for this skill. Set interactively during skillshare new or omitted entirely.

category: quality

Available categories: library, verification, data, automation, scaffold, quality, cicd, runbook, infra.

license​

The skill's license identifier. Displayed during installation to help with compliance decisions.

license: MIT

When present, skillshare install shows the license in the skill selection prompt and confirmation screen:

  • Single skill: Displayed as License: MIT in the skill info box
  • Multi-skill repo: Appended to the skill name in the selection list (e.g., my-skill (MIT))

This is purely informational — it does not block installation. Common values: MIT, Apache-2.0, GPL-3.0, BSD-3-Clause, ISC.

The metadata Block​

The metadata: block is a structured YAML object for deployment and behavioral fields. This aligns with the Agent Skills ecosystem convention used across 30+ AI CLI tools.

---
name: my-skill
description: My custom skill
metadata:
  targets: [claude]
  pattern: reviewer
  domain: python
---

Currently, targets is the only metadata field that skillshare processes. Other fields (like pattern, domain, interaction) are preserved in the frontmatter but not used by skillshare — they may be consumed by other tools in the ecosystem.

For backward compatibility, skillshare also reads a top-level targets field. If both are present, metadata.targets takes precedence.

Custom Fields​

You can add any custom top-level fields:

---
name: my-skill
description: My custom skill
author: Your Name
version: 1.0.0
---

Custom top-level fields are stored in the frontmatter but not used by skillshare itself.

Markdown Body​

The body contains instructions for the AI. Write it as if you're instructing a human assistant.

Good practices:

  • Clear, specific instructions
  • Examples of inputs and expected outputs
  • Edge cases and error handling
  • When to use (and when NOT to use)

Example:

# Code Review

You are a code reviewer. Analyze code for:
- Bugs and potential issues
- Style and consistency
- Performance concerns
- Security vulnerabilities

## When to Use

Use this skill when the user asks you to review code, find bugs, or improve code quality.

## Instructions

1. Read the provided code carefully
2. Identify issues in order of severity
3. Suggest specific improvements with code examples
4. Be constructive and explain your reasoning

## Example

User: "Review this function"
```python
def add(a, b):
  return a + b

Response: "The function looks correct but could benefit from type hints..."


---

## Centralized Metadata

When you install a skill, skillshare records its metadata in `.metadata.json` (centralized for all skills):

```json
{
  "skills": [
    {
      "name": "pdf",
      "source": "anthropics/skills/skills/pdf",
      "type": "github",
      "installed_at": "2026-01-20T15:30:00Z",
      "repo_url": "https://github.com/anthropics/skills.git",
      "subdir": "skills/pdf",
      "version": "abc1234"
    }
  ]
}

Each skill entry includes:

FieldDescription
nameSkill directory name
sourceOriginal install source input
typeSource type (github, local, etc.)
installed_atInstallation timestamp
repo_urlGit clone URL (git sources only)
subdirSubdirectory path (monorepo sources only)
versionGit commit hash at install time

This is used by skillshare update and skillshare check to know where to fetch updates from.

Don't edit this file manually.

Creating a Skill​

skillshare new my-skill

This creates:

~/.config/skillshare/skills/my-skill/
└── SKILL.md  (with template)

Edit the generated SKILL.md and run skillshare sync to deploy.

Validating Skills​

skillshare doctor

Checks for:

  • Valid SKILL.md format
  • Required name field
  • Valid frontmatter YAML
  • Name collisions

See Also​