Creating Agent Skills

Overview

Agent Skills is an open standard for portable AI agent capabilities. One SKILL.md file works across Codex CLI, GitHub Copilot, and Amp.

Official Spec: https://agentskills.io/specification

Installation Directories

Tool	Location
Codex CLI	.agents/skills/{skill-name}/SKILL.md
GitHub Copilot	.github/skills/{skill-name}/SKILL.md
Amp	.agents/skills/{skill-name}/SKILL.md

Directory Structure

```

my-skill/                 # Must match frontmatter `name`
├── SKILL.md              # Required - main definition
├── scripts/              # Optional - executable code
├── references/           # Optional - additional docs
└── assets/               # Optional - static resources

Frontmatter Specification

Required Fields

---
name: skill-name
description: What it does and when to use it
---

Optional Fields

---
name: pdf-processing
description: Extracts and processes PDF content. Use for document analysis and text extraction.
license: MIT
compatibility: Requires pdftotext, poppler-utils
allowed-tools: Bash(pdftotext:*) Read Write
metadata:
  category: document-processing
  version: 1.0.0
---

Name Validation

```

✅ Valid: pdf-processing, code-review, data-analysis
❌ Invalid: PDF-Processing (uppercase), -pdf (leading hyphen), pdf--processing (consecutive hyphens)

Description Best Practices

```yaml

# ❌ BAD - Too vague
description: Helps with PDFs

# ❌ BAD - Missing use cases
description: Extracts text from PDFs

# ✅ GOOD - Functionality + use cases
description: Extracts and processes PDF content. Use for document analysis, text extraction, and form data parsing.

Body Content

Markdown instructions after frontmatter. No format restrictions, but recommended sections: