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:

---
name: code-review
description: Reviews code for best practices and security issues. Use when analyzing PRs or conducting audits.
---

## Overview

Brief description of capabilities.

## Process

1. Step-by-step workflow
2. With clear actions

## Guidelines

- Bullet points for rules
- Best practices

## Examples

Code samples showing usage.

Progressive Disclosure

Skills use tiered loading to optimize context:

1. Metadata (~100 tokens): name + description load at startup
2. Activation (<5000 tokens): Full SKILL.md loads when selected
3. On-demand: Supporting files load when referenced

Keep SKILL.md under 500 lines for efficient context usage.

Supporting Files

scripts/

#!/usr/bin/env python3
# scripts/extract.py
import sys
# Self-contained with clear dependencies

Complete Example

Type Guard

function isUser(obj: unknown): obj is User {
  return typeof obj === 'object' && obj !== null && 'id' in obj && 'name' in obj;
}

Validation

Use the validation tool:

skills-ref validate ./my-skill

Quick Checklist

• Frontmatter:
• name is 1-64 chars, lowercase alphanumeric + hyphens
• name matches parent directory name
• description is 1-1024 chars
• description includes functionality AND use cases
• Content:
• Under 500 lines for efficient loading
• Clear instructions agents can follow
• Examples for complex operations
• Structure:
• Directory named exactly as name field
• SKILL.md at directory root
• Supporting files in appropriate subdirectories

Cross-Tool Compatibility

The SKILL.md format is identical across implementations. To port:

# Codex → Copilot
mv .agents/skills/my-skill .github/skills/my-skill

# Copilot → Codex/Amp
mv .github/skills/my-skill .agents/skills/my-skill