Files
Willie be8f8b2874 fix(hub): read the same tags for drafts and the index (#909)
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.
2026-11-14 23:52:45 +08:00

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:

  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

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: 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.

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 name field
  • Valid frontmatter YAML
  • Name collisions

See Also