The index and the draft builder read a skill's tags with different readers, so the same SKILL.md could publish different tags depending on the path: - The index accepted only the comma form (tags: git, workflow). A YAML list became "[git" and "review]", and a block list produced nothing. - Drafts accepted only a YAML list, so the documented comma form produced no tags, and metadata.tags replaced the root field. After #901 the index ignores metadata, which made the two disagree there as well. Both now call readSkillTags. It reads the root field only, in either form: a list comes from the decoded frontmatter, and the comma form from the existing line scan. The scan also unwraps a one-line list, so a skill whose frontmatter YAML rejects on another line (for example an unquoted colon in the description) no longer publishes bracketed fragments. Tags under metadata are custom data and are not read by either path. The skill format page says so in all five locales.
8.9 KiB
sidebar_position
| sidebar_position |
|---|
| 5 |
Skill Format
The structure and metadata of a skillshare skill.
:::tip 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:
- YAML frontmatter — Metadata
- 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
A YAML list such as tags: [git, workflow] works too. Only the top-level field is read; tags under metadata is custom data.
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]
:::info 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.
:::
| Value | Behavior |
|---|---|
| (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 Pi, 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: MITin 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.
Nested mappings and lists are preserved, including provenance and unknown fields:
metadata:
type: Skill
status: stable
generated:
by: human:alex
at: "2026-11-13T00:00:00Z"
sources:
- id: agentskills
resource: https://agentskills.io/specification
Root name and description identify the skill; nested fields with those names do not replace them. metadata.type describes custom content and does not change the installation source type recorded in .metadata.json. Sync preserves the SKILL.md content. Native clients may impose their own metadata requirements.
Custom Fields
Prefer metadata for custom fields. Existing custom top-level fields are preserved, but native clients may restrict which fields they accept:
---
name: my-skill
description: My custom skill
metadata:
author: Your Name
version: 1.0.0
---
Skillshare preserves these custom values without assigning behavior to them.
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
{
"version": 1,
"entries": {
"pdf": {
"source": "anthropics/skills/skills/pdf",
"type": "github-subdir",
"installed_at": "2026-01-20T15:30:00Z",
"repo_url": "https://github.com/anthropics/skills.git",
"subdir": "skills/pdf",
"version": "abc1234"
}
}
}
Each skill entry includes:
| Field | Description |
|---|---|
| Entry key | Skill path relative to the source directory (for example pdf or frontend/react-skill) |
source |
Original install source input |
type |
Source type (github, local, etc.) |
installed_at |
Installation timestamp |
repo_url |
Git clone URL (git sources only) |
subdir |
Subdirectory path (monorepo sources only) |
version |
Git 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
namefield - Valid frontmatter YAML
- Name collisions
See Also
- new — Create a skill with the correct template
- Creating Skills — Full guide to writing skills
- Best Practices — Naming and organization tips