How to Structure Content for GitHub Copilot Skills

Learn how to create portable, resource-rich Agent Skills for GitHub Copilot that work across VS Code, CLI, and coding agents with best practices for structure, progressive disclosure, and cross-platform compatibility.
Author

Dario Airoldi

Published

January 13, 2026

How to Structure Content for GitHub Copilot Skills

⚠️ Preview Feature: Agent Skills were introduced in VS Code 1.107 (December 2024) and are currently in Preview. APIs and behaviors may change in future releases.

Agent Skills (SKILL.md) represent a new paradigm for extending GitHub Copilot with portable, resource-rich capabilities that work across multiple platforms.
Unlike instruction files (which apply silently based on file patterns) or agent files (which define VS Code-specific personas), skills are on-demand workflows that include scripts, templates, and examples alongside instructions.

This article explores how to structure skill files effectively, leverage progressive disclosure for optimal performance, and decide when skills are the right choice over other customization types.

Table of Contents

🎯 Understanding Skill Files

What Are Agent Skills?

Agent Skills are folders containing instructions, scripts, and resources that GitHub Copilot can load on-demand to perform specialized tasks. They follow an open standard called agentskills.io that enables portability across multiple AI agents—not just GitHub Copilot.

Key Characteristics

Aspect Description
File SKILL.md in a dedicated directory
Activation Automatic based on description matching your prompt
Scope Task-specific, loaded on-demand
Visibility Discoverable - Copilot lists available skills
Portability Cross-platform (VS Code, CLI, GitHub coding agent)
Resources Can include scripts, templates, examples
Standard Open standard (agentskills.io)

The Progressive Disclosure System

Skills use a three-level loading system to minimize context consumption:

┌─────────────────────────────────────────────────────────────────┐
│  Level 1: SKILL DISCOVERY (Always Loaded)                       │
│  ├── name: "webapp-testing"                                     │
│  └── description: "Automated testing workflow for web apps..."  │
│      (~50-100 tokens per skill)                                 │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼ (When prompt matches description)
┌─────────────────────────────────────────────────────────────────┐
│  Level 2: INSTRUCTIONS LOADING                                  │
│  └── SKILL.md body content                                      │
│      (~500-1500 tokens)                                         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼ (When referenced by Copilot)
┌─────────────────────────────────────────────────────────────────┐
│  Level 3: RESOURCE ACCESS                                       │
│  ├── templates/component.test.js                                │
│  ├── examples/login-form-tests.js                               │
│  └── scripts/setup-test-env.sh                                  │
│      (Loaded only when explicitly needed)                       │
└─────────────────────────────────────────────────────────────────┘

This progressive disclosure means:

  • ✅ Level 1 is always in context (lightweight metadata only)
  • ✅ Level 2 loads only when your request matches the skill
  • ✅ Level 3 loads only when Copilot needs specific resources

Skills vs Other Customization Types

Feature Skills Instructions Prompts Agents
File SKILL.md .instructions.md .prompt.md .agent.md
Activation Auto (description match) Auto (file pattern) On-demand (/name) Agent picker
Resources ✅ Scripts, templates ❌ None ❌ None ❌ None
Cross-platform ✅ VS Code, CLI, coding agent, SDK ⚠️ VS Code + GitHub.com ❌ VS Code only ❌ VS Code only
Tool Control ❌ Limited ❌ None ✅ Full ✅ Full
Handoffs ❌ Not supported ❌ Not supported ❌ Not supported ✅ Full orchestration
Standard Open (agentskills.io) VS Code-specific VS Code-specific VS Code-specific

When to Use Skills

✅ Use skills for:

  • Cross-platform workflows - Tasks that should work in VS Code, CLI, and coding agent
  • Resource-rich tasks - Workflows requiring templates, scripts, or examples
  • Shareable capabilities - Functionality you want to contribute to community repositories
  • Specialized procedures - Testing, debugging, deployment workflows with step-by-step guidance
  • Standardized processes - Company-wide procedures that need portable documentation

❌ Don’t use skills for:

  • File-specific coding standards - Use instruction files with applyTo patterns
  • Complex tool orchestration - Use agents with full tool configuration
  • Handoff workflows - Use agents with handoff capabilities
  • VS Code-specific features - Use agents or prompts for IDE-specific functionality
  • Quick one-time tasks - Use chat commands or inline chat

📋 Skill File Structure

Directory Layout

Every skill requires a dedicated directory with a SKILL.md file:

.github/skills/webapp-testing/          # Skill directory
├── SKILL.md                            # Required: Instructions + metadata
├── templates/                          # Optional: Reusable templates
│   ├── component.test.js
│   └── integration.test.js
├── examples/                           # Optional: Real-world examples
│   ├── login-form-tests.js
│   └── data-table-tests.js
├── scripts/                            # Optional: Automation scripts
│   └── setup-test-env.sh
└── README.md                           # Optional: Usage notes

Storage Locations

Workspace Skills (Shared with Team)

# Recommended location
.github/skills/skill-name/SKILL.md

# Legacy location (backward compatibility)
.claude/skills/skill-name/SKILL.md

Personal Skills (User-Level)

# Windows
%USERPROFILE%\.copilot\skills\skill-name\SKILL.md

# macOS/Linux
~/.copilot/skills/skill-name/SKILL.md

# Legacy location
~/.claude/skills/skill-name/SKILL.md

SKILL.md Format

The SKILL.md file is a Markdown document with required YAML frontmatter:

---
name: webapp-testing
description: Automated testing workflow for web applications with Jest and React Testing Library. Use when generating test suites, setting up test infrastructure, or debugging test failures.
---

# Web Application Testing Skill

[Skill body with instructions, workflow, and resource references]

YAML Frontmatter Fields

Required Fields

Field Type Constraints Example
name String Lowercase, hyphens only, max 64 chars "webapp-testing"
description String Max 1024 chars, include use cases "Testing workflow for... Use when..."

Name Field Requirements

# ✅ Valid names
name: webapp-testing
name: security-review
name: kubernetes-deployment

# ❌ Invalid names
name: WebApp Testing     # No spaces or uppercase
name: test               # Too generic
name: my-super-awesome-testing-skill-for-react-apps-v2  # Too long (>64 chars)

Description Field Best Practices

The description serves two critical purposes:

  1. Discovery - Copilot shows this when listing available skills
  2. Matching - Copilot uses this to decide when to load the skill
# ✅ Good: Specific capabilities AND use cases
description: >
  Automated testing workflow for web applications with Jest and 
  React Testing Library. Use when generating test suites, setting 
  up test infrastructure, or debugging test failures.

# ❌ Bad: Vague, no use case guidance
description: Helps with testing

# ❌ Bad: Too long (exceeds 1024 chars)
description: [500+ word essay about testing philosophy...]

Description Formula:

[What it does] + [Technologies/tools involved] + "Use when" + [specific scenarios]

Body Content Structure

The body contains detailed instructions in Markdown format:

---
name: webapp-testing
description: Automated testing workflow for web applications...
---

# Web Application Testing Skill

## Purpose
[One paragraph: what this skill accomplishes]

## When to Use
[Bullet list of specific scenarios that trigger this skill]

## Workflow
[Step-by-step procedure with clear actions]

## Examples
[References to examples/ directory or inline examples]

## Resources
[Links to templates, scripts, documentation in the skill directory]

Required Sections

Section Purpose Content
Purpose Quick overview 1-2 sentences describing the skill’s goal
When to Use Activation guidance Bullet list of scenarios
Workflow Core instructions Step-by-step procedure

Referencing Resources

Always use relative paths when referencing files within the skill directory:

## Templates

Use the [component test template](./templates/component.test.js) as a starting point.

## Examples

For complex scenarios, see:
- [Login form tests](./examples/login-form-tests.js) - Authentication flows
- [Data table tests](./examples/data-table-tests.js) - Dynamic data handling

## Scripts

Run [setup-test-env.sh](./scripts/setup-test-env.sh) to configure the test environment.

❌ Don’t use:

  • Absolute paths: /home/user/project/.github/skills/...
  • URLs to external resources (include them in the skill directory instead)

✍️ Writing Effective Skills

Core Principles

1. Optimize for Discovery

The description field determines when Copilot loads your skill. Include keywords users might use in their prompts:

# ✅ Good: Multiple matching keywords
description: >
  Generate comprehensive test suites for React components using Jest 
  and React Testing Library. Use when writing unit tests, creating 
  integration tests, testing user interactions, or validating 
  component rendering.

# Keywords: test, React, Jest, Testing Library, unit tests, 
#           integration tests, user interactions, rendering

2. Progressive Detail

Structure content so Copilot can extract what it needs without reading everything:

## Quick Reference
[Essential patterns - 5-10 lines]

## Detailed Workflow
[Full procedure - 50-100 lines]

## Deep Dive
[Comprehensive explanations - references to external docs]

3. Self-Contained Resources

Include everything needed to complete the task within the skill directory:

webapp-testing/
├── SKILL.md
├── templates/
│   ├── unit-test.template.js      # Copy-paste ready
│   └── integration-test.template.js
├── examples/
│   ├── basic-component.test.js    # Simple case
│   └── complex-form.test.js       # Edge cases
└── config/
    └── jest.config.example.js     # Configuration reference

4. Clear Activation Triggers

In the “When to Use” section, be explicit about scenarios:

## When to Use

Activate this skill when:
- **Generating tests**: "Write tests for this component"
- **Debugging failures**: "My test is failing with [error]"
- **Setting up infrastructure**: "Configure Jest for this project"
- **Learning patterns**: "Show me testing best practices for React"

Do NOT use this skill for:
- End-to-end (E2E) testing with Playwright/Cypress
- Backend API testing
- Performance benchmarking

Content Length Guidelines

Skills have more flexibility than instruction files because they load on-demand:

Content Type Recommended Length Rationale
Description 100-200 chars Balance specificity with brevity
SKILL.md body 500-1500 words Enough detail for complex workflows
Templates 20-50 lines each Minimal boilerplate, users will expand
Examples 30-100 lines each Show pattern without full implementation

Length Comparison with Other Files

File Type Max Recommended Loading
Skill (SKILL.md body) 1500 words On-demand
Instruction file 600 words Always (when pattern matches)
Prompt file 800 words On-demand
Agent file 1000 words When agent active

Skills can be longer because they only load when explicitly needed.

Example: Complete Skill

---
name: security-code-review
description: Security-focused code review following OWASP Top 10 guidelines. Use when reviewing pull requests for vulnerabilities, auditing authentication code, or validating input sanitization.
---

# Security Code Review Skill

## Purpose

Perform comprehensive security-focused code reviews to identify vulnerabilities before they reach production. This skill applies OWASP Top 10 guidelines and common security patterns.

## When to Use

- Reviewing pull requests for security issues
- Auditing authentication/authorization code
- Validating input sanitization and output encoding
- Checking for common vulnerability patterns (SQLi, XSS, CSRF)
- Reviewing cryptographic implementations

## Workflow

### 1. Identify Attack Surface

First, identify entry points where untrusted data enters the system:
- HTTP request parameters (query strings, body, headers)
- File uploads
- Database inputs from other systems
- Environment variables and configuration

### 2. Authentication & Authorization

Check for:
- [ ] Proper authentication on all protected endpoints
- [ ] Role-based access control (RBAC) enforcement
- [ ] Session management security
- [ ] Password hashing with modern algorithms (bcrypt, Argon2)

### 3. Input Validation

Verify:
- [ ] All user input validated server-side
- [ ] Parameterized queries for database operations
- [ ] Output encoding for HTML/JavaScript contexts
- [ ] File upload restrictions (type, size, content)

### 4. Data Protection

Ensure:
- [ ] Sensitive data encrypted at rest and in transit
- [ ] No secrets in source code or logs
- [ ] Proper error handling (no stack traces to users)
- [ ] Secure cookie flags (HttpOnly, Secure, SameSite)

## Checklists

See [checklists/owasp-top-10.md](./checklists/owasp-top-10.md) for detailed review criteria.

## Common Vulnerabilities

Reference [examples/common-vulns.md](./examples/common-vulns.md) for code patterns to watch for.

## Resources

- [OWASP Top 10](https://owasp.org/www-project-top-ten/)
- [CWE/SANS Top 25](https://cwe.mitre.org/top25/)

⚠️ Critical Limitations and Boundaries

Understanding what skills cannot do is essential for choosing the right customization type.

Technical Limitations

1. No Tool Control

Skills cannot specify which tools are available to Copilot. Unlike agents and prompts:

<!-- In an agent file, you can specify tools -->
tools:
  - codebase
  - terminal
  - editFiles

<!-- In a skill, you CANNOT do this -->
<!-- Skills rely on whatever tools the current context provides -->

Workaround: Suggest tool usage in your instructions:

## Workflow

1. Use the codebase search to find existing test patterns
2. Use the terminal to run the test suite
3. Use file editing to create new test files

2. No Handoff Capabilities

Skills cannot orchestrate multi-agent workflows:

<!-- Agent files support handoffs -->
handoffs:
  - agent: security-expert
    when: "security concerns identified"

<!-- Skills do NOT support handoffs -->
<!-- Each skill is a standalone unit -->

When this matters: If your workflow requires passing control between specialized agents, use agent files instead.

3. Limited Activation Control

Activation is based solely on description matching—you cannot:

  • Specify file patterns (like applyTo in instructions)
  • Exclude specific contexts
  • Require explicit invocation
# ❌ NOT SUPPORTED in skills
applyTo: "**/*.test.js"
excludeAgent: "code-review"

4. No User Input Variables

Skills don’t support prompt variables like prompt files do:

<!-- Prompt files support variables -->
Generate a ${componentType} component named ${name}

<!-- Skills must use generic instructions -->
Generate a component following the patterns below...

5. Preview Feature Stability

As a preview feature, skills may have:

  • Behavior changes between VS Code versions
  • Incomplete documentation
  • Edge cases not fully handled
  • API changes without deprecation warnings

Platform Limitations

VS Code Specific

Feature VS Code CLI Coding Agent SDK Apps
Skill discovery ✅ ✅ ✅ ✅
Resource loading ✅ ✅ ✅ ✅
Script execution ⚠️ With approval ⚠️ With approval ⚠️ With approval ⚠️ App-managed
UI feedback ✅ Rich ⚠️ Text only ⚠️ Async ⚠️ App-managed

Security Considerations

Scripts in skills require user approval before execution:

## Scripts

Run [setup-test-env.sh](./scripts/setup-test-env.sh) to configure the environment.
<!-- User will be prompted to approve this command -->

Configure auto-approval carefully in VS Code settings:

{
  "github.copilot.chat.terminal.allowedCommands": [
    "npm test",
    "npm run lint"
  ]
}

🚫 Common Pitfalls and How to Avoid Them

Pitfall 1: Vague Descriptions

Problem: Generic descriptions cause skills to activate inappropriately or not at all.

❌ Bad example:

name: testing
description: Helps with testing

This matches too broadly (“test my patience”) or not at all (doesn’t mention specific technologies).

✅ Solution: Be specific with technologies and use cases:

name: react-testing
description: >
  Generate Jest unit tests and React Testing Library integration tests 
  for React components. Use when creating test suites, testing user 
  interactions, or debugging test failures in React applications.

Pitfall 2: Missing Use Cases in Description

Problem: Copilot can’t determine when to activate the skill.

❌ Bad example:

description: Security-focused code review following OWASP guidelines.

✅ Solution: Include “Use when” trigger phrases:

description: >
  Security-focused code review following OWASP Top 10 guidelines. 
  Use when reviewing pull requests for vulnerabilities, auditing 
  authentication code, or validating input sanitization.

Pitfall 3: External Resource Dependencies

Problem: Skill references resources that may not be available or may change.

❌ Bad example:

## Templates

Download the test template from https://example.com/templates/test.js

✅ Solution: Include all resources in the skill directory:

## Templates

Use the [test template](./templates/test.js) included in this skill.

Pitfall 4: Absolute File Paths

Problem: Hardcoded paths break when skills are shared or moved.

❌ Bad example:

Reference the configuration at /home/user/project/config/jest.config.js

✅ Solution: Use relative paths from the skill directory:

Reference the [configuration template](./config/jest.config.example.js)

Pitfall 5: Over-Scoped Skills

Problem: Skills that try to do everything become too large and unfocused.

❌ Bad example:

name: complete-development-workflow
description: >
  Full development workflow including testing, deployment, code review,
  documentation, performance optimization, security auditing, database
  migrations, CI/CD setup, monitoring configuration...

✅ Solution: Create focused skills with clear boundaries:

# Skill 1: testing-workflow
name: testing-workflow
description: Generate and run test suites...

# Skill 2: deployment-workflow  
name: deployment-workflow
description: Deploy applications to production...

# Skill 3: security-review
name: security-review
description: Review code for security vulnerabilities...

Pitfall 6: Duplicating Built-in Capabilities

Problem: Creating skills for things Copilot already does well.

❌ Bad example:

name: code-explanation
description: Explain what code does
# Copilot already has /explain command

✅ Solution: Focus on specialized, domain-specific workflows:

name: legacy-code-modernization
description: >
  Analyze legacy code patterns and suggest modern alternatives.
  Use when migrating jQuery to React, upgrading .NET Framework 
  to .NET 8, or converting callback-based code to async/await.

Pitfall 7: No Testing Before Sharing

Problem: Skills that work in your environment may fail elsewhere.

Checklist before sharing:

🎨 Advanced Patterns

Pattern 1: Skill Composition

Create specialized skills that work together:

.github/skills/
├── testing-core/              # Base testing utilities
│   ├── SKILL.md
│   └── templates/
├── react-testing/             # React-specific (references testing-core)
│   ├── SKILL.md
│   └── templates/
└── api-testing/               # API-specific (references testing-core)
    ├── SKILL.md
    └── templates/

In react-testing/SKILL.md:

## Prerequisites

This skill builds on [testing-core](../testing-core/SKILL.md) patterns.
For base test utilities, see [testing-core templates](../testing-core/templates/).

Pattern 2: Environment-Specific Variants

Create skills with environment-aware instructions:

---
name: kubernetes-deployment
description: Deploy applications to Kubernetes clusters...
---

# Kubernetes Deployment Skill

## Environment Detection

First, determine the target environment:

### Development (minikube/kind)
```bash
kubectl config current-context
## If contains "minikube" or "kind", use development settings

Staging (AWS EKS / Azure AKS)

[Staging-specific instructions]

Production

[Production-specific instructions with extra safeguards]

Pattern 3: Progressive Complexity

Structure skills with increasing detail levels:

## Quick Start (5 minutes)
[Minimal steps to get started]

## Standard Workflow (30 minutes)
[Complete workflow with best practices]

## Advanced Configuration (1+ hours)
[Deep customization and edge cases]

Pattern 4: Checklist-Driven Skills

Include actionable checklists for complex workflows:

### Pre-Deployment Checklist

### Code Quality
- [ ] All tests passing
- [ ] No linting errors
- [ ] Code review approved

### Security
- [ ] Secrets in vault (not in code)
- [ ] Dependencies scanned
- [ ] Security review complete

### Infrastructure
- [ ] Database migrations ready
- [ ] Rollback plan documented
- [ ] Monitoring alerts configured

Pattern 5: Template Hierarchies

Organize templates by complexity and use case:

templates/
├── minimal/                   # Bare minimum to start
│   └── component.test.js
├── standard/                  # Best practices included
│   └── component.test.js
└── comprehensive/             # Full coverage patterns
    └── component.test.js

Reference in SKILL.md:

### Templates

Choose based on your needs:
- [Minimal](./templates/minimal/) - Quick start, add tests incrementally
- [Standard](./templates/standard/) - Recommended for most projects
- [Comprehensive](./templates/comprehensive/) - Full coverage patterns

🧪 Testing and Validation

How to Test Skills

1. Enable Skills in VS Code

First, ensure skills are enabled:

// settings.json
{
  "chat.useAgentSkills": true
}

2. Verify Skill Discovery

Ask Copilot about available skills:

User: "What skills are available in this workspace?"
Copilot: [Lists skills with names and descriptions]

Verify your skill appears with correct name and description.

3. Test Activation with Various Prompts

Test that your skill activates for intended use cases:

## Should activate testing skill
"Generate unit tests for this React component"
"Help me debug this failing test"
"Set up Jest for this project"

## Should NOT activate testing skill
"Write documentation for this function"
"Deploy this to production"

4. Verify Resource Loading

Test that templates and examples load correctly:

User: "Use the component test template to test this Button component"
Copilot: [Should reference templates/component.test.js content]

5. Cross-Platform Testing

If your skill should work across platforms, test in:

  • VS Code Copilot Chat
  • Copilot CLI (if available)
  • GitHub Copilot coding agent (PR workflows)

Validation Checklist

Before committing a skill:

Debugging Skills

Skill Not Activating

  1. Check description matches prompt keywords
  2. Verify skill is in correct location (.github/skills/)
  3. Ensure chat.useAgentSkills is enabled
  4. Check VS Code version (1.107+)

Resources Not Loading

  1. Verify relative paths are correct
  2. Check files exist in skill directory
  3. Ensure files aren’t gitignored
  4. Test with explicit resource reference

Script Execution Issues

  1. Check script has execute permissions
  2. Verify cross-platform compatibility
  3. Review VS Code terminal approval settings

💡 Decision Framework

Use this flowchart to decide when to use skills:

START: Need to extend Copilot's capabilities?
│
├─ Does it require scripts, templates, or examples?
│  │
│  YES─ Does it need to work across platforms (CLI, coding agent)?
│  │    │
│  │    YES─ ✅ USE SKILL
│  │    │
│  │    NO─ Is it a complex multi-agent workflow?
│  │        │
│  │        YES─ ✅ USE AGENT FILE (with handoffs)
│  │        │
│  │        NO─ ✅ USE SKILL (for resource bundling)
│  │
│  NO─ Is it file-specific coding standards?
│      │
│      YES─ ✅ USE INSTRUCTION FILE (with applyTo)
│      │
│      NO─ Is it a one-time task?
│          │
│          YES─ ✅ USE PROMPT FILE or CHAT
│          │
│          NO─ Is it a persistent persona?
│              │
│              YES─ ✅ USE AGENT FILE
│              │
│              NO─ Does it need tool orchestration?
│                  │
│                  YES─ ✅ USE AGENT FILE
│                  │
│                  NO─ ✅ USE PROMPT FILE

Quick Reference Table

Scenario Solution Rationale
Testing workflow with templates Skill Resources + cross-platform
Python PEP 8 coding standards Instruction File-specific, always active
Generate React form component Prompt One-time task, no resources
Security reviewer persona Agent Persistent behavior, tool control
Deployment procedure with scripts Skill Scripts + cross-platform
Complex code review workflow Agent Handoffs to specialists
API documentation generation Skill or Prompt Depends on template needs
Company coding standards Instruction Always applied, no resources

Skills vs Agents: Detailed Comparison

Capability Skills Agents
Bundled resources ✅ Templates, scripts, examples ❌ Instructions only
Tool configuration ❌ Use defaults ✅ Full control
Handoff orchestration ❌ Not supported ✅ Multi-agent workflows
Cross-platform ✅ VS Code, CLI, coding agent, SDK ❌ VS Code only
Activation Auto (description match) Manual (agent picker)
Open standard ✅ agentskills.io ❌ VS Code-specific
Execution modes Standard only Local, Background, Cloud
Maturity Preview (v1.107+) Stable (v1.106+)

Choose Skills when: You need portable, resource-rich workflows
Choose Agents when: You need VS Code-specific orchestration and tool control

🔄 Migration Guidance

When to Migrate Existing Customizations to Skills

Consider migrating to skills if:

  1. Cross-platform requirement - Your workflow needs to work in CLI or coding agent
  2. Resource bundling - You have templates/scripts that should travel with instructions
  3. Community sharing - You want to contribute to skill repositories
  4. Standardization - You want to follow the agentskills.io open standard

Migration Examples

From Instruction File to Skill

Before: .github/instructions/testing.instructions.md

---
applyTo: "**/*.test.ts"
---
## Testing Standards
Always use Jest with React Testing Library...

After: .github/skills/testing-workflow/SKILL.md

---
name: testing-workflow
description: Testing workflow with Jest and RTL. Use when writing tests...
---
## Testing Workflow Skill

### Standards
Always use Jest with React Testing Library...

### Templates
Use [component test template](./templates/component.test.ts)...

Key changes:

  • Add name and description (remove applyTo)
  • Create directory structure
  • Add templates/examples as files
  • Update references to relative paths

From Prompt File to Skill

Before: .github/prompts/generate-tests.prompt.md

---
description: Generate unit tests for components
---
## Generate Tests
Create comprehensive unit tests for the selected component...

After: .github/skills/test-generation/SKILL.md

---
name: test-generation
description: Generate unit tests for React components. Use when...
---
## Test Generation Skill

### Workflow
1. Analyze component structure
2. Use [test template](./templates/component.test.tsx)
3. Cover rendering, interactions, edge cases

### Templates
[Include actual template files]

Key changes:

  • Change YAML fields (name required for skills)
  • Add templates directory with actual files
  • Expand description with “Use when” scenarios

What NOT to Migrate

Keep as Instructions:

  • File-specific coding standards (applyTo patterns)
  • Rules that should always apply silently
  • Simple guidelines without resource needs

Keep as Agents:

  • Complex multi-agent workflows with handoffs
  • Tasks requiring specific tool configurations
  • VS Code-specific functionality
  • Long-running background tasks

Keep as Prompts:

  • Quick one-time tasks
  • Tasks with user input variables
  • Simple task definitions without resources

🎯 Conclusion

Agent Skills represent a new paradigm for extending AI coding assistants with portable, resource-rich capabilities. While currently in preview, they offer unique advantages that complement existing customization options.

Key takeaways:

  1. Skills bundle resources with instructions - Include templates, scripts, and examples alongside guidance
  2. Progressive disclosure optimizes performance - Only loads what’s needed, when needed
  3. Cross-platform portability is the killer feature - Works across VS Code, CLI, and coding agent
  4. Description quality determines activation success - Include specific technologies AND “Use when” scenarios
  5. Use relative paths exclusively - Ensures skills remain portable
  6. Skills complement, don’t replace, other customizations - Use the right tool for each need
  7. Preview status means expect changes - APIs and behaviors may evolve

Choosing the Right Customization

Need Solution
Portable workflow with templates Skill
File-specific coding standards Instruction
One-time task execution Prompt
Persistent persona with tools Agent
Multi-agent orchestration Agent (with handoffs)

By understanding when to use skills versus other customization types, you can build a powerful, maintainable system that enhances Copilot’s effectiveness across all your development workflows.

📚 References

Implementation Guidance

For repository-specific implementation rules, see:

Official Documentation

VS Code: Agent Skills [📘 Official]
Microsoft’s official documentation for Agent Skills in VS Code. Covers the complete skill structure, YAML frontmatter requirements, progressive disclosure system, and resource organization. Essential reference for understanding how VS Code processes and loads skills.

agentskills.io [📘 Official]
The open standard specification for Agent Skills. Defines the cross-platform format that enables skills to work across multiple AI agents, not just GitHub Copilot. Reference for understanding portability requirements and standard compliance.

VS Code: Copilot Customization Overview [📘 Official]
Comprehensive overview of all Copilot customization options including instructions, prompts, agents, and skills. Explains how different customization types work together and provides guidance on choosing the right approach.

VS Code v1.107 Release Notes [📘 Official]
December 2024 release introducing Agent Skills as a preview feature alongside Agent HQ, background agents, and Claude skills support. Documents the initial capabilities and known limitations of the skills feature.

Community Resources

GitHub: Awesome Copilot Repository [📗 Verified Community]
Community-curated collection of Copilot customizations including example skills. Browse for real-world examples and patterns. Demonstrates practical skill organization and content structure.

Anthropic: Skills Repository [📗 Verified Community]
Reference skills repository from Anthropic. High-quality examples following the agentskills.io standard. Useful for understanding cross-platform skill design patterns.

skills.sh — Vercel Skill Directory [📗 Verified Community]
Vercel’s curated directory of agent skills, including an MCP builder and MCP apps skills. Browse it for ready-made skills you can drop into your project or use as design references.

GitHub Blog: How to Use GitHub Copilot [📗 Verified Community]
Official GitHub blog post on maximizing Copilot effectiveness. While focused on general usage, provides insights on context management that apply to skill design.