Skip to main content

​
What are Agent Skills?

Agent Skills are self-contained folders containing a SKILL.md instruction file and optional bundled resources (scripts, templates, reference data) that enhance AI capabilities for specialized tasks. Based on the Agent Skills specification, skills provide progressive disclosure—loaded only when needed for specific tasks.

Browse the Skills Catalog

Explore 200+ ready-to-use skills for different technologies, frameworks, and workflows.

​
How Skills Differ from Other Resources

Skills are unique in the GitHub Copilot ecosystem because they can bundle assets alongside instructions:

Agents

Specialized Copilot configurations with instructions and tool access. Pure behavior, no bundled files.

Skills

Instructions PLUS bundled resources (scripts, templates, data). Self-contained capabilities.

Instructions

Coding standards applied to file patterns. For consistent style and best practices.

Plugins

Curated packages that bundle agents, skills, and commands into installable themes.

​
Skill Structure

Each skill is a folder containing a SKILL.md file with YAML frontmatter: 
skills/appinsights-instrumentation/
├── SKILL.md                    # Required: Instructions with frontmatter
├── scripts/                    # Optional: Helper scripts
│   └── appinsights.ps1
├── references/                 # Optional: Reference documentation
│   ├── ASPNETCORE.md
│   ├── NODEJS.md
│   └── PYTHON.md
└── examples/                   # Optional: Code examples
    └── appinsights.bicep

​
SKILL.md Frontmatter

Every skill requires YAML frontmatter with name and description: 
---
name: appinsights-instrumentation
description: 'Instrument a webapp to send useful telemetry data to Azure App Insights'
---

# AppInsights instrumentation

This skill enables sending telemetry data...

​
Frontmatter Fields

​
name
string
required
Skill identifier matching the folder name (lowercase with hyphens, 1-64 characters)
​
description
string
required
Brief description of what the skill does AND when to use it (10-1024 characters). Must be wrapped in single quotes.

​
Bundled Assets

Skills can include various types of bundled resources:

​
Scripts

Executable helper scripts that automate tasks:
The copilot-usage-metrics skill includes 4 shell scripts:
copilot-usage-metrics/
├── SKILL.md
├── get-org-metrics.sh
├── get-org-user-metrics.sh
├── get-enterprise-metrics.sh
└── get-enterprise-user-metrics.sh
These scripts retrieve GitHub Copilot usage data via GitHub CLI and REST API.

​
Templates

Reusable code templates or diagram templates:
The excalidraw-diagram-generator skill includes 8 diagram templates:
excalidraw-diagram-generator/
├── SKILL.md
├── templates/
│   ├── flowchart-template.excalidraw
│   ├── mindmap-template.excalidraw
│   ├── sequence-diagram-template.excalidraw
│   ├── class-diagram-template.excalidraw
│   ├── er-diagram-template.excalidraw
│   ├── data-flow-diagram-template.excalidraw
│   ├── business-flow-swimlane-template.excalidraw
│   └── relationship-template.excalidraw
└── references/
    ├── element-types.md
    └── excalidraw-schema.md
Templates provide starting points for different diagram types.

​
References

Detailed reference documentation loaded on-demand:
The aspire skill includes 9 reference documents:
aspire/
├── SKILL.md
└── references/
    ├── architecture.md
    ├── cli-reference.md
    ├── dashboard.md
    ├── deployment.md
    ├── integrations-catalog.md
    ├── mcp-server.md
    ├── polyglot-apis.md
    ├── testing.md
    └── troubleshooting.md
The SKILL.md tells agents when to load specific reference files.

​
Assets & Examples

Code samples, configuration files, or other data:
The create-web-form skill includes 24 reference files:
create-web-form/
├── SKILL.md
└── references/
    ├── form-basics.md
    ├── html-form-elements.md
    ├── css-styling.md
    ├── javascript.md
    ├── accessibility.md
    ├── security.md
    ├── php-forms.md
    ├── python-flask.md
    └── ... (16 more)
Comprehensive coverage of web form development across multiple technologies.

​
When to Use Skills

Use Skills When

  • You need bundled scripts or utilities
  • Templates or code samples are required
  • Reference data enhances the workflow
  • The task is complex and repeatable
  • Progressive disclosure is valuable

Use Instructions When

  • Enforcing coding standards
  • Applying best practices to file patterns
  • No bundled resources needed
  • Simple, pattern-based guidance

Use Agents When

  • Need MCP server integrations
  • Specialized tool access required
  • Specific AI model preferences
  • Custom behavior without files

Use Plugins When

  • Installing related resources as a bundle
  • Curating themed toolkits
  • Sharing comprehensive workflows

​
Real-World Skill Examples

​
Azure & Cloud

appinsights-instrumentation/
├── SKILL.md
├── scripts/appinsights.ps1
├── examples/appinsights.bicep
└── references/
    ├── ASPNETCORE.md
    ├── NODEJS.md
    ├── PYTHON.md
    └── AUTO.md

​
Documentation & Diagrams

game-engine/
├── SKILL.md
├── assets/
│   ├── 2d-maze-game.md
│   ├── 2d-platform-game.md
│   ├── paddle-game-template.md
│   ├── simple-2d-engine.md
│   └── gameBase-template-repo.md
└── references/
    ├── game-engine-core-principles.md
    ├── techniques.md
    ├── algorithms.md
    └── ... (6 more)

​
Testing & Data Analysis

datanalysis-credit-risk/
├── SKILL.md
├── scripts/example.py
└── references/
    ├── analysis.py
    └── func.py

​
Progressive Disclosure Pattern

Skills implement progressive disclosure—detailed references are loaded only when needed:
1

Initial Load

The SKILL.md provides an overview and decision tree
2

Contextual Reference

The skill instructs the agent to load specific reference files based on the user’s context
3

Execute Scripts

Bundled scripts are run when the workflow requires them
4

Use Templates

Templates are copied and customized for the specific use case
Example from the appinsights-instrumentation skill: 
## Guidelines

### Collect context information
Find out the (programming language, application framework, hosting) tuple...

### Prefer auto-instrument if possible
If the app is a C# ASP.NET Core app hosted in Azure App Service, 
use [AUTO guide](references/AUTO.md)...

### Manually instrument
- If the app is an ASP.NET Core app, see [ASPNETCORE guide](references/ASPNETCORE.md)
- If the app is a Node.js app, see [NODEJS guide](references/NODEJS.md)
- If the app is a Python app, see [PYTHON guide](references/PYTHON.md)
The agent reads the main SKILL.md, determines context, then loads only the relevant reference file.

​
Creating Your Own Skills

Contributing Skills

Learn how to create and contribute new skills to the community

​
Skill Creation Checklist

  • Create folder with lowercase-hyphenated name
  • Add SKILL.md with required frontmatter
  • Organize bundled assets in scripts/, references/, templates/, or assets/
  • Keep individual files under 5MB
  • name matches folder name (1-64 chars)
  • description explains WHAT and WHEN (10-1024 chars)
  • Description wrapped in single quotes
  • Clear “When to use this skill” section
  • Step-by-step workflow
  • References to bundled assets with relative paths
  • Progressive disclosure (load references on-demand)
  • Scripts are executable and documented
  • Templates are tested and complete
  • References are comprehensive but modular
  • All assets referenced in SKILL.md

​
Agent Skills Specification

Skills in this repository follow the agentskills.io specification for maximum compatibility across AI platforms:
  • Portable: Skills work across different AI assistants and platforms
  • Self-contained: All dependencies bundled in the skill folder
  • Progressive: Detailed content loaded only when needed
  • Discoverable: Rich metadata enables automatic skill discovery

Read the Full Specification

Learn about the complete Agent Skills specification

Build docs developers (and LLMs) love

Get started for freeTalk to us