Files
skillshare/website/docs/understand/skill-format.md
T
Willie 22e7028747 docs: update target/filtering docs for agent filters and metadata.targets
- Add --agent-mode, --add-agent-include/exclude flags to target command docs
- Update filtering reference with agent filter examples and storage paths
- Prefer metadata.targets over top-level targets in all examples
- Note agent filter limitations (merge/copy only, requires agents path)
- Update skill-format docs with metadata.targets precedence note
- Update built-in skill references/targets.md with agent filter examples
2026-04-09 03:14:58 +08:00

339 lines
8.0 KiB
Markdown

---
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:
1. **YAML frontmatter** — Metadata
2. **Markdown body** — Instructions for the AI
---
## Basic Structure
```markdown
---
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
```yaml
name: my-skill
```
**Rules:**
- Lowercase letters, numbers, hyphens, underscores
- Must start with a letter or number
- Should be unique across all skills
**Examples:**
```yaml
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.
```yaml
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`.
```yaml
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:
```yaml
# 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](/docs/reference/targets/supported-targets).
**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](/docs/reference/targets/configuration#skill-level-targets).
**Example — Claude-only skill:**
```markdown
---
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>`.
```yaml
pattern: reviewer
```
Available patterns: `tool-wrapper`, `generator`, `reviewer`, `inversion`, `pipeline`. See [Skill Design Patterns](/docs/understand/philosophy/skill-design-patterns) for details on each.
### `category`
The use-case category for this skill. Set interactively during `skillshare new` or omitted entirely.
```yaml
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.
```yaml
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](https://developers.googleblog.com/en/5-agent-skill-design-patterns-every-adk-developer-should-know/) used across 30+ AI CLI tools.
```yaml
---
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:
```yaml
---
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:**
```markdown
# 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:
| Field | Description |
|-------|-------------|
| `name` | Skill directory name |
| `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
```bash
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
```bash
skillshare doctor
```
Checks for:
- Valid SKILL.md format
- Required `name` field
- Valid frontmatter YAML
- Name collisions
---
## See Also
- [new](/docs/reference/commands/new) — Create a skill with the correct template
- [Creating Skills](/docs/how-to/daily-tasks/creating-skills) — Full guide to writing skills
- [Best Practices](/docs/how-to/daily-tasks/best-practices) — Naming and organization tips