---
name: Creating Agent Skills
slug: creating-agent-skills
category: AI Engineering
description: Creating Agent Skills explains the SKILL.md format for portable agent capabilities across Codex CLI, GitHub Copilot, and Amp. Use it when authoring skills with the required frontmatter, directory structure, and validation rules.
github: "https://github.com/AgentWorkforce/relay/tree/main/.agents/skills/creating-agent-skills-skill"
language: TypeScript
stars: 801
forks: 64
install: "npx degit https://github.com/AgentWorkforce/relay/tree/main/.agents/skills/creating-agent-skills-skill ~/.claude/skills/creating-agent-skills-skill"
installs_to: ~/.claude/skills/creating-agent-skills-skill
source_path: .agents/skills/creating-agent-skills-skill/SKILL.md
collection_size: 25
category_size: 2451
collection_url: "https://dirskills.com/collections/AgentWorkforce/relay"
added: 2026-08-23T05:18:45.240Z
last_synced: 2026-08-23T05:18:45.240Z
canonical_url: "https://dirskills.com/skills/creating-agent-skills"
---

# Creating Agent Skills

Creating Agent Skills explains the SKILL.md format for portable agent capabilities across Codex CLI, GitHub Copilot, and Amp. Use it when authoring skills with the required frontmatter, directory structure, and validation rules.

**Install:**

```bash
npx degit https://github.com/AgentWorkforce/relay/tree/main/.agents/skills/creating-agent-skills-skill ~/.claude/skills/creating-agent-skills-skill
```

## README

# Creating Agent Skills

Use when creating Agent Skills packages (SKILL.md format) for Codex CLI, GitHub Copilot, or Amp - provides the agentskills.io specification with frontmatter constraints, directory structure, and validation rules

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

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

#### Optional Fields

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

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

```markdown
---
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/

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

### Complete Example

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

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

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

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