Skill Authoring

This skill guides creation of valid, well-structured Agent Skills following the agentskills.io specification.

Directory Structure

Every skill is a directory named after the skill itself:

skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable scripts
├── references/       # Optional: supplementary documentation
└── assets/           # Optional: templates, static resources

The directory name must exactly match the name field in SKILL.md.

SKILL.md Format

SKILL.md must begin with YAML frontmatter, followed by Markdown instructions.

Required Fields

Optional Fields

Minimal Template

---
name: my-skill
description: Does X and Y. Use when the user asks about Z.
---

# My Skill

Instructions here.

Full Template

---
name: my-skill
description: Extracts and transforms X. Use when working with X files or when the user mentions Y or Z.
license: MIT
compatibility: Requires python3 and internet access
metadata:
  version: "1.0"
allowed-tools: Bash(python3:*) Read Write
---

# My Skill

Brief overview.

## Steps

1. Step one
2. Step two

## Examples

Input: ...
Output: ...

## Edge Cases

- Handle ...

Writing Good Instructions

Body content (after frontmatter) has no format restrictions — write whatever helps agents perform the task.

Recommended sections:

• Step-by-step instructions
• Input/output examples
• Common edge cases and how to handle them

Size guidelines:

• Keep SKILL.md under 500 lines (~5000 tokens)
• Move detailed reference material to references/ files
• Agents load references/ files on demand — keep them focused and small

Writing a Good description

The description is how agents decide whether to activate a skill. Make it specific:

• State what the skill does (actions, outputs)
• State when to use it (trigger phrases, task types)
• Include domain-specific keywords

Good:

description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

Poor:

description: Helps with PDFs.

Versioning

Skill versions are tracked centrally in the repository's skills.json file. When you modify an existing skill or add a new one, you must update its version information using Semantic Versioning (SemVer):

• Patch (x.x.Y): Minor fixes, typo corrections, or small clarifications that do not change how the skill is fundamentally used.
• Minor (x.Y.x): Adding new steps, examples, or optional capabilities in a backward-compatible manner.
• Major (Y.x.x): Breaking changes to instructions, changing the allowed tools, or fundamentally altering the skill's purpose.

When making a change:

1. Locate the skill's entry in the skills array inside skills.json (or add a new entry for new skills).
2. Bump the version field according to the SemVer rules above (start at "1.0.0" for new skills).
3. If the skill uses the optional metadata.version field in its SKILL.md frontmatter, ensure that is updated as well to match.

Validation

Run the reference validator if available:

skills-ref validate ./my-skill

Common validation errors:

• name contains uppercase letters or spaces → use lowercase hyphens only
• name doesn't match directory name → rename one to match the other
• description is empty or too vague → expand with what/when language
• Consecutive hyphens in name (e.g. my--skill) → not allowed

Checklist Before Publishing

• Directory name matches name field exactly
• name is lowercase with hyphens, no consecutive hyphens
• description explains both what it does and when to trigger it
• Body instructions are clear, actionable, and under 500 lines
• Large reference material is in references/ not inline
• Scripts in scripts/ are self-contained with helpful error messages
• compatibility field included only if environment requirements exist
• Version in skills.json has been updated following Semantic Versioning