Create Agent Skill

Guides you through authoring a new Agent Skill that complies with the agentskills.io specification.

Specification constraints (must follow exactly)

The SKILL.md body has no format restrictions — write whatever helps agents perform the task. Keep it under 500 lines; move detail to references/.

Directory layout

<skill-name>/
├── SKILL.md            # Required
├── references/         # Optional — load on demand, keep files focused
├── scripts/            # Optional — executable code (see scripts guide)
└── assets/             # Optional — templates, static files

Step-by-step workflow

1. Gather intent

Before writing anything, clarify:

• What does this skill do? One clear sentence.
• When should an agent activate it? List trigger phrases and contexts.
• What is the expected output? File, command, explanation, ...
• Are there environment dependencies? Binaries, network access, credentials?
• Should there be scripts? If tasks are repetitive or complex, yes.

2. Choose the skill name

# Name must match the directory you will create
# Good names: pdf-processing, git-workflow, terminal-cli, code-review
# Bad: PDFProcessing, pdf_processing, -pdf, pdf--processing

3. Create the directory

mkdir -p skills/<skill-name>/references
mkdir -p skills/<skill-name>/scripts   # only if scripts are needed

Tip: specify license: CC BY-NC-SA 4.0 in your SKILL.md frontmatter. A standalone LICENSE file is optional—the spec only requires the field, not a separate file. Keep it simple.

4. Write SKILL.md

Start with the frontmatter, then the body (the spec only cares about the field):

---
name: <skill-name>
license: CC BY-NC-SA 4.0   # a single line is all that's required by agentskills.io
description: >
  One paragraph. First sentence: what it does.
  Remaining sentences: when to activate it, what trigger
  phrases should cause an agent to load this skill.
---

# <Title>

Brief intro paragraph.

## When to use this skill
...

## Step-by-step instructions
...

## Examples
...

Description writing guide:

• Include both what (capabilities) and when (trigger contexts).
• List specific keywords agents can match: tool names, file types, verbs.
• Be specific enough that the agent activates this skill and not a generic fallback.
• Bad: "Helps with PDFs." — too vague, no trigger signals.
• Good: "Extracts text and tables from PDF files, fills forms, merges documents. Use when the user mentions PDFs, forms, or document extraction." — clear capability + trigger.

5. Add reference files (if SKILL.md would exceed 500 lines)

# Create focused reference files — one topic per file
cat > skills/<skill-name>/references/advanced.md << 'EOF'
# Advanced <Topic> Reference
...
EOF

Reference them from SKILL.md:

For complete options, see `references/advanced.md`.

6. Add scripts (if needed)

See references/scripts-guide.md for full script design rules.

Quick rules:

• No interactive prompts — accept all input via flags or env vars.
• Always implement --help.
• Send structured data (JSON/CSV) to stdout, diagnostics to stderr.
• Support --dry-run for destructive operations.
• Use exit codes meaningfully (0 = success, 1 = user error, 2 = system error).

7. Validate

# Install the reference validator
pip install skills-ref --break-system-packages

# Validate your skill
skills-ref validate ./skills/<skill-name>

# Preview the XML that agents will see in their context
skills-ref to-prompt ./skills/<skill-name>

8. Add GitHub topic

After pushing your repo, add the agent-skills topic so others can discover your skill at https://github.com/topics/agent-skills.

Progressive disclosure reminder

An agent loads your skill in three stages:

1. Startup — only name + description (~100 tokens). Make the description do its job.
2. Activation — full SKILL.md body. Keep under 500 lines.
3. On demand — references/ and scripts/ files, only when the agent needs them.

Never put everything in SKILL.md. If you are approaching 500 lines, split.

Reference files in this skill

• references/scripts-guide.md — detailed guide for writing agentic scripts
• references/examples.md — annotated example skills (good and bad)