Create Agent Skill

When to Use This Skill

Use this skill when:

• •User wants to create a new agent skill
• •User wants to package knowledge or workflows for AI agents
• •User mentions "skill", "agent capability", or "reusable instructions"
• •User wants to extend agent capabilities with domain expertise

Directory Structure

Every skill requires this minimum structure:

skill-name/
└── SKILL.md          # Required: instructions + metadata

Optional directories for complex skills:

skill-name/
├── SKILL.md          # Required
├── scripts/          # Optional: executable code (Python, Bash, JS)
├── references/       # Optional: additional documentation
└── assets/           # Optional: templates, images, data files

Important: Place skills in .github/skills/ for repository-level skills.

SKILL.md Format

Required Frontmatter

---
name: skill-name
description: A description of what this skill does and when to use it.
---

Frontmatter Field Rules

Name Validation

✅ Valid names:

• •pdf-processing
• •code-review
• •data-analysis

❌ Invalid names:

• •PDF-Processing (uppercase not allowed)
• •-pdf (cannot start with hyphen)
• •pdf- (cannot end with hyphen)
• •pdf--processing (consecutive hyphens not allowed)

Writing Good Descriptions

✅ Good description:

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:

description: Helps with PDFs.

The description should:

1. •State what the skill DOES (capabilities)
2. •State WHEN to use it (trigger conditions)
3. •Include keywords agents will match against

Body Content Best Practices

After frontmatter, write Markdown instructions. Recommended sections:

1. •When to use this skill - Clear trigger conditions
2. •Step-by-step instructions - How to perform the task
3. •Examples - Inputs and expected outputs
4. •Edge cases - Common issues and how to handle them
5. •File references - Links to scripts or references if needed

Progressive Disclosure

Structure content for efficient context use:

Keep SKILL.md under 500 lines. Move detailed reference material to separate files.

Step-by-Step: Creating a New Skill

1. •Choose a name - lowercase, hyphens only, descriptive
2. •Create directory - .github/skills/{skill-name}/
3. •Write SKILL.md with:
   • •Valid frontmatter (name + description minimum)
   • •Clear instructions in the body
   • •Examples where helpful
4. •Add optional directories if needed:
   • •scripts/ for executable code
   • •references/ for detailed documentation
   • •assets/ for templates and resources
5. •Validate the skill structure

Template

Use this template for new skills:

---
name: {skill-name}
description: {What it does}. Use when {trigger conditions}.
metadata:
  author: {your-org}
  version: "1.0"
---

# {Skill Title}

## When to Use This Skill

Use this skill when:
- {Condition 1}
- {Condition 2}

## Instructions

{Step-by-step instructions for the agent}

## Examples

### Example 1: {Scenario}

**Input:** {What the user asks}

**Output:** {What the agent produces}

## Edge Cases

- {Edge case 1}: {How to handle}
- {Edge case 2}: {How to handle}

File References

When referencing other files, use relative paths from skill root:

See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py

Keep references one level deep. Avoid deeply nested chains.

Validation

After creating a skill, verify:

1. •Directory name matches name field exactly
2. •name follows naming rules (lowercase, hyphens, no consecutive)
3. •description is non-empty and under 1024 characters
4. •SKILL.md has valid YAML frontmatter
5. •Body content is clear and actionable

Reference

• •Specification: https://agentskills.io/specification
• •Examples: https://github.com/anthropics/skills
• •Validation tool: https://github.com/agentskills/agentskills/tree/main/skills-ref