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
---

Field	Constraints
name	1-64 chars, lowercase alphanumeric + hyphens, no leading/trailing/consecutive hyphens, must match parent directory
description	1-1024 chars, explains functionality AND use cases

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
---

Field	Constraints
license	Short reference (e.g., MIT, Apache-2.0)
compatibility	1-500 chars, environment requirements
allowed-tools	Space-delimited pre-approved tools (experimental)
metadata	Arbitrary string key-value pairs

Name Validation

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

Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$

Description Best Practices

# ❌ 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.

Include:

• What the skill does
• When to activate it (keywords agents search for)
• Specific use cases

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/

Executable code agents can invoke:

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

references/

Additional documentation:

• REFERENCE.md - Technical details
• FORMS.md - Templates
• Domain-specific files

assets/

Static resources: templates, diagrams, lookup tables.

Reference with relative paths: scripts/extract.py, references/REFERENCE.md

Complete Example

---
name: typescript-expert
description: Expert TypeScript assistance with strict typing and modern patterns. Use for TypeScript projects requiring type safety, generics, or advanced type manipulation.
license: MIT
compatibility: Requires Node.js 18+, TypeScript 5+
---

You are an expert TypeScript developer.

## Guidelines

- Always use strict type checking
- Prefer `unknown` over `any`
- Use type guards for runtime checking
- Leverage template literal types

## Best Practices

- Export types from dedicated `.types.ts` files
- Use `readonly` for immutable data
- Prefer interfaces for objects, types for unions

## Examples

### Type Guard

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

## Validation

Use the validation tool:
```bash
skills-ref validate ./my-skill

Checks:

• YAML frontmatter validity
• Name format compliance
• Required fields presence
• Directory name matches name field

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

No content changes required.