Creating Agent Skills

Entities

Skill Directory Structure

Based on Agent Skills Specification:

skill-name/
├── SKILL.md              # Required: Core skill definition
├── scripts/              # Optional: Executable code
│   └── extract.py
├── references/           # Optional: Additional documentation
│   ├── REFERENCE.md      # Technical reference (recommended)
│   └── domain.md
└── assets/               # Optional: Static resources
    ├── template.json
    └── schema.yaml

Directory Descriptions

SKILL.md Components

1. •Frontmatter (YAML): Metadata defining when the skill triggers
2. •Body (Markdown): Instructions for executing the skill

States

• •Planning: Gathering requirements and trigger phrases
• •Drafting: Writing SKILL.md and supporting files
• •Validating: Checking structure and content quality
• •Complete: Skill ready for use

Actions

Define Frontmatter

Write YAML frontmatter with required and optional fields:

---
name: skill-name
description: >
  What the skill does and when to use it. Include specific keywords
  that help agents identify relevant tasks.
license: Apache-2.0
compatibility: Requires git, docker
metadata:
  author: example-org
  version: "1.0"
---

Field Constraints:

Naming Best Practices:

Use gerund form (verb + -ing) for skill names to clearly describe the activity:

Good:

name: processing-pdfs
name: analyzing-spreadsheets
name: generating-reports
name: reviewing-code

Avoid:

name: pdf-helper      # vague - what does "help" mean?
name: utils           # generic - no indication of purpose
name: data-tools      # unclear - what operations?
name: anthropic-skill # reserved words not allowed

Consistent naming helps:

• •Claude understand what a skill does at a glance
• •Reference skills in documentation and conversations
• •Maintain a cohesive skill library

Description Best Practices:

• •Start with a verb describing what the skill does
• •Include when to use it (trigger conditions)
• •Include specific keywords for agent task matching

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.

Write Skill Body

The Markdown body contains skill instructions. Recommended sections:

• •Step-by-step instructions
• •Examples of inputs and outputs
• •Common edge cases

Writing Style:

• •Use imperative or infinitive verb forms
• •Avoid second-person pronouns ("you", "your")
• •Keep under 500 lines (< 5000 tokens recommended)
• •Move detailed content to references/ directory

Good:

Parse the configuration file.
Validate input before processing.

Bad:

You should parse the configuration file.

Organize Supporting Files

scripts/ directory:

• •Self-contained or clearly document dependencies
• •Include helpful error messages
• •Handle edge cases gracefully

references/ directory:

• •REFERENCE.md for detailed technical reference
• •Domain-specific files as needed
• •Keep files focused (smaller = less context usage)
• •Link from SKILL.md: See [reference](references/REFERENCE.md)

assets/ directory:

• •Templates (document, configuration)
• •Images (diagrams, examples)
• •Data files (lookup tables, schemas)

Validate Skill

Use skills-ref for validation:

skills-ref validate ./skill-name

Manual validation checklist in validation-checklist.md.

Constraints

• •name must match parent directory name exactly
• •name allows only lowercase letters, numbers, hyphens (no --, no leading/trailing -)
• •description must be 1-1024 characters
• •Keep SKILL.md under 500 lines
• •Keep file references one level deep (avoid nested chains)
• •All referenced files must exist