# Creating Agent Skills

Use when creating Agent Skills packages (SKILL.md format) for Codex CLI, GitHub...

- Repository: https://github.com/AgentWorkforce/relay (1088 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add AgentWorkforce/relay --skill creating-agent-skills -g -a claude-code -y`
Codex: `npx skills add AgentWorkforce/relay --skill creating-agent-skills -g -a codex -y`
Cursor: `npx skills add AgentWorkforce/relay --skill creating-agent-skills -g -a cursor -y`
Gemini CLI: `npx skills add AgentWorkforce/relay --skill creating-agent-skills -g -a gemini-cli -y`

## Description

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

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

The rest: https://github.com/AgentWorkforce/relay/blob/HEAD/.agents/skills/creating-agent-skills-skill/SKILL.md