Skill authoring guide

Package layout

my-skill/
├── SKILL.md          required: instructions + frontmatter
├── references/       optional: docs the skill can read on demand
├── scripts/          optional: code the skill can run
├── assets/           optional: templates, images, fonts
├── agents/           optional: sub-agent definitions
├── examples/         optional: sample inputs and outputs
└── LICENSE           optional

• Upload the folder as a ZIP (SKILL.md at the root or inside one top-level folder), or just a SKILL.md.
• Up to 5 MB and 200 files. Paths must be relative, without .., symlinks or hidden files.
• Don't include manifest.json or CHANGELOG.md unless you want your own changelog: the marketplace generates the manifest (with checksums) and a changelog from your version notes.

Writing SKILL.md

SKILL.md starts with YAML frontmatter, then Markdown instructions:

---
name: changelog-writer
description: Turns a list of merged pull requests into a user-facing changelog grouped by feature, fix and breaking change. Use when preparing release notes.
license: MIT
---

# Changelog writer

## When to use
Use when you have merged PR titles or commit messages for a release and need
release notes a user can read.

## Steps
1. Group the changes into Features, Fixes and Breaking changes.
2. Rewrite each item in plain language, starting with a verb.
3. Link to the PR when a URL is given.

## Reference
See references/style-guide.md for tone and formatting rules.

• name (required): lowercase letters, digits and hyphens, at most 64 characters. It becomes the skill's URL and install folder, and must be unique in the marketplace.
• description (required): at most 1024 characters. Say what the skill does and when to use it; assistants use this to decide when to load the skill.
• license (optional): an identifier such as MIT or Apache-2.0.
• The first # Heading becomes the title shown in the marketplace.
• Keep SKILL.md focused; move long reference material into references/ and point to it.

Platform compatibility

Each published skill shows which tools it works with. Tools that read skill folders (such as Claude Code) or accept a ZIP upload (such as Claude.ai) get the full package. Tools without skill folders get the SKILL.md instructions only, as a rules file or a prompt, so scripts and agents don't run there; a skill that relies on them is marked experimental for those tools.

A package that fails the SKILL.md checks above is unsupported everywhere. See Install for the platforms and where each one installs skills.

Passing the security scan

Every submission is scanned for risky patterns. Findings don't block a submission, but reviewers see them and the grade is shown publicly. To keep a clean grade:

• Don't tell the model to ignore other instructions or to hide what it does from the user.
• Never ask for passwords, API keys or tokens, and don't read credential files.
• Ship scripts as readable source in scripts/; don't pipe downloads into a shell or use eval.
• Don't commit keys or tokens, and avoid large encoded blobs.

The full list of checks and how grades work.

Publishing and versions

1. Submit your package with a category, a version (semantic, e.g. 1.2.0) and optional tags, license and change notes.
2. It is scanned, then waits for a reviewer. Track it, and see any reviewer notes, on your dashboard.
3. Once approved it is published. Until then it stays private.
4. To update a skill, submit a new package with the same name. It becomes a new version and replaces the published one when approved; earlier versions stay in the version history.