Agent Skills (SKILL.md)

Folders of instructions, scripts, and resources that agents load on-demand for specialized tasks.

Structure

.github/skills/<skill-name>/
├── SKILL.md           # Required (name must match folder)
├── scripts/           # Executable code
├── references/        # Docs loaded as needed
└── assets/            # Templates, boilerplate

Locations

Path	Scope
`.github/skills/<name>/`	Project
`.agents/skills/<name>/`	Project
`.claude/skills/<name>/`	Project
`~/.copilot/skills/<name>/`	Personal
`~/.claude/skills/<name>/`	Personal

SKILL.md Format

---
name: skill-name              # Required: 1-64 chars, lowercase alphanumeric + hyphens, must match folder
description: 'What and when to use. Max 1024 chars.'
---

Body

What the skill accomplishes
When to use (triggers and use cases)
Step-by-step procedures
References to resources: [script](./scripts/test.js)

Template

---
name: webapp-testing
description: 'Test web applications using Playwright. Use for verifying frontend, debugging UI, capturing screenshots.'
---

# Web Application Testing

## When to Use
- Verify frontend functionality
- Debug UI behavior

## Procedure
1. Start the web server
2. Run [test script](./scripts/test.js)
3. Review screenshots in `./screenshots/`

Progressive Loading

Discovery (~100 tokens): Agent reads name and description
Instructions (<5000 tokens): Loads SKILL.md body when relevant
Resources: Additional files load only when referenced

Keep file references one level deep from SKILL.md.

When to Use

Repeatable, on-demand workflows with bundled assets (scripts, templates, reference docs).

Core Principles

Keyword-rich descriptions: Include trigger words for discovery
Progressive loading: Keep SKILL.md under 500 lines; use reference files
Relative paths: Always use ./ for skill resources
Self-contained: Include all procedural knowledge to complete the task

Anti-patterns

Vague descriptions: "A helpful skill" doesn't enable discovery
Monolithic SKILL.md: Everything in one file instead of references
Name mismatch: Folder name doesn't match name field
Missing procedures: Descriptions without step-by-step guidance

2.4 KiB Raw Blame History