Agent-Skills

# Agent Skills File Guidelines

Instructions for creating effective and portable Agent Skills that enhance GitHub Copilot with specialized capabilities, workflows, and bundled resources.

What Are Agent Skills?

Agent Skills are self-contained folders with instructions and bundled resources that teach AI agents specialized capabilities. Unlike custom instructions (which define coding standards), skills enable task-specific workflows that can include scripts, examples, templates, and reference data.

Key characteristics:

- **Portable**: Works across VS Code, Copilot CLI, and Copilot coding agent

- **Progressive loading**: Only loaded when relevant to the user's request

- **Resource-bundled**: Can include scripts, templates, examples alongside instructions

- **On-demand**: Activated automatically based on prompt relevance

Directory Structure

Skills are stored in specific locations:

| Location | Scope | Recommendation |

|----------|-------|----------------|

| `.github/skills/<skill-name>/` | Project/repository | Recommended for project skills |

| `.claude/skills/<skill-name>/` | Project/repository | Legacy, for backward compatibility |

| `~/.github/skills/<skill-name>/` | Personal (user-wide) | Recommended for personal skills |

| `~/.claude/skills/<skill-name>/` | Personal (user-wide) | Legacy, for backward compatibility |

Each skill **must** have its own subdirectory containing at minimum a `SKILL.md` file.

Required SKILL.md Format

Frontmatter (Required)

---
name: webapp-testing
description: 'Toolkit for testing local web applications using Playwright. Use when asked to verify frontend functionality, debug UI behavior, capture browser screenshots, check for visual regressions, or view browser console logs. Supports Chrome, Firefox, and WebKit browsers.'
license: Complete terms in LICENSE.txt
---

| Field | Required | Constraints |

|-------|----------|-------------|

| `name` | Yes | Lowercase, hyphens for spaces, max 64 characters (e.g., `webapp-testing`) |

| `description` | Yes | 10–1024 characters, clear capabilities AND use cases, wrapped in single quotes |

| `license` | No | Reference to LICENSE.txt (e.g., `Complete terms in LICENSE.txt`) or SPDX identifier |

Description Best Practices

**CRITICAL**: The `description` field is the PRIMARY mechanism for automatic skill discovery. Copilot reads ONLY the `name` and `description` to decide whether to load a skill. If your description is vague, the skill will never be activated.

**What to include in description:**

1. **WHAT** the skill does (capabilities)

2. **WHEN** to use it (specific triggers, scenarios, file types, or user requests)

3. **Keywords** that users might mention in their prompts

**Good description:**

description: 'Toolkit for testing local web applications using Playwright. Use when asked to verify frontend functionality, debug UI behavior, capture browser screenshots, check for visual regressions, or view browser console logs. Supports Chrome, Firefox, and WebKit browsers.'

**Poor description:**

description: 'Web testing helpers'

The poor description fails because:

- No specific triggers (when should Copilot load this?)

- No keywords (what user prompts would match?)

- No capabilities (what can it actually do?)

Body Content

The body contains detailed instructions that Copilot loads AFTER the skill is activated. Recommended sections:

| Section | Purpose |

|---------|---------|

| `# Title` | Brief overview of what this skill enables |

| `## When to Use This Skill` | List of scenarios (reinforces description triggers) |

| `## Prerequisites` | Required tools, dependencies, environment setup (if applicable) |

| `## Step-by-Step Workflows` | Numbered steps for repeatable procedures (build, deploy, setup) |

| `## Gotchas` | Proactive warnings about non-obvious behavior ("never do X because Y") |

| `## Troubleshooting` | Reactive fixes for known issues ("if you see X, try Y") |

| `## References` | Links