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:

• Metadata (~100 tokens): name

• description load at startup

• Activation (<5000 tokens): Full SKILL.md loads when selected

• 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

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.