Creating Agent Skills

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

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)

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.