Chapter 14: Agent Skills — Writing & Managing
Part V: Agentic Development Prerequisites: Chapter 13: Copilot Coding Agent — Setup & Operations GH-100 Exam Mapping: Beyond GH-100 — Enterprise Copilot mastery Verified: 2026-02-01 against official documentation
1. Introduction
Learning Objectives
After completing this chapter, you will be able to:
- Explain the agent skills architecture including YAML frontmatter metadata, skill loading mechanics, and the distinction between skills, custom instructions, and custom agents
- Create repository-level skills in the
.github/skills/directory using theSKILL.mdformat with correct frontmatter fields and effective descriptions - Design skill directory structures that include supporting scripts, examples, and documentation that Copilot can reference during task execution
- Apply enterprise best practices for skill versioning, naming conventions, discovery, and sharing across teams in organizations with 200+ developers
- Test and debug skills by validating frontmatter syntax, verifying activation triggers, and iterating on instruction quality
- Differentiate between custom instructions, agent skills, and custom agents, and select the appropriate mechanism for each enterprise use case
Exam Domain Coverage
| Domain | Topics in This Chapter |
|---|---|
| Beyond GH-100 — Enterprise Copilot mastery | Agent skills architecture, YAML frontmatter format, skill storage levels (repository/personal), skill resolution and loading, skill vs. custom instructions vs. custom agents, enterprise skill library management |
Chapter Overview
In Chapter 13: Copilot Coding Agent -- Setup & Operations, you learned how the Copilot coding agent autonomously executes multi-step development tasks by opening pull requests, running tests, and iterating on code. However, the coding agent's effectiveness is directly proportional to the quality of context it receives. Without domain-specific guidance, the agent relies on general-purpose knowledge that may not align with your organization's conventions, frameworks, or architectural patterns. Agent skills solve this problem by providing structured, task-specific instructions that the agent loads on demand.
Agent skills are an open standard -- originally created by Anthropic and adopted by GitHub -- that allows you to teach Copilot how to perform specialized tasks in a specific, repeatable way. Unlike custom instructions (which are always loaded into context for every interaction), skills are modular knowledge packages that Copilot selectively activates based on the relevance of your request. Each skill lives in its own directory, contains a SKILL.md file with YAML frontmatter, and can include supporting scripts, examples, and documentation. This architecture keeps context efficient: Copilot reads only the lightweight metadata (name and description) for all available skills, then loads the full instructions only for the skills it determines are relevant to the current task.
For enterprise teams managing hundreds of repositories across multiple product lines, agent skills represent a significant opportunity. Rather than embedding the same conventions into every repository's custom instructions file, teams can build a shared skill library that standardizes how the coding agent handles common tasks -- from generating database migrations to reviewing Terraform plans to creating release notes. This chapter covers everything you need to write, organize, test, and manage agent skills at enterprise scale. By the end, you will have built a working skill from scratch and understand how to roll out a skill management strategy across your organization.
2. Theory & Deep Dive
2.1 What Are Copilot Agent Skills?
Agent skills are folders of instructions, scripts, and resources that Copilot can load when relevant to improve its performance in specialized tasks. Think of building a skill as creating an onboarding guide for a new team member: instead of explaining the same process every time, you write it down once, and the agent follows it whenever the situation arises.
Skills work across all Copilot agent surfaces:
- Copilot coding agent -- the autonomous agent that opens PRs (Pull Requests) on GitHub (see Chapter 13)
- Agent mode in VS Code -- the interactive agent mode in Visual Studio Code
- GitHub Copilot CLI -- the command-line interface for Copilot
This cross-surface compatibility is a key architectural decision. A skill written for the coding agent works identically when a developer invokes it from their IDE or terminal, providing consistent behavior regardless of the interaction surface.
Skills vs. Custom Instructions vs. Custom Agents
Enterprise teams frequently ask how skills relate to the other customization mechanisms. The following table clarifies the distinction:
| Feature | Custom Instructions | Agent Skills | Custom Agents |
|---|---|---|---|
| Activation | Always loaded into context | Auto-loaded only when relevant | Explicitly invoked by name (e.g., @security-reviewer) |
| Scope | Repository-wide norms and conventions | Task-specific capabilities | Workflow-specific personas |
| Contains | Text guidelines | Instructions + scripts + examples + resources | Prompts + tool configurations + MCP (Model Context Protocol) servers |
| Storage | .github/copilot-instructions.md | .github/skills/<skill-name>/SKILL.md | .github/agents/<agent-name>.md |
| Best for | Coding standards, architecture notes, preferred libraries | Detailed, reusable procedures for specific task types | Named personas that orchestrate tools for end-to-end workflows |
| Portability | Per-repository | Cross-agent open standard | Cross-environment within GitHub ecosystem |
The recommended approach is to use all three mechanisms together:
- Custom instructions for universal, always-on repository context (coding style, build commands, architecture overview)
- Agent skills for detailed, reusable task-specific knowledge that should load only when relevant
- Custom agents for named personas that combine instructions, skills, tools, and MCP servers into a cohesive workflow
Enterprise Scenario: A payments platform company with 250 developers uses custom instructions in every repository to enforce their Go coding standards and microservice naming conventions. They maintain a shared skill library with 15 skills covering tasks like "generate database migration," "review Terraform plan diff," and "create OpenAPI spec from handler code." Their platform team has built three custom agents --
@security-reviewer,@release-manager, and@migration-assistant-- that combine these skills with specific tool configurations and MCP server access for end-to-end workflows.
2.2 The SKILL.md File Format
Every skill is defined by a SKILL.md file -- a Markdown file with YAML frontmatter. The frontmatter provides metadata that Copilot reads to determine when a skill should be activated, while the Markdown body contains the actual instructions.
Required Frontmatter Fields
---
name: terraform-plan-review
description: >
Review Terraform plan diffs for security, cost, and best-practice issues.
Use for Terraform, plan, diff, IAM, network, and cost review topics.
---
name(required): A unique identifier for the skill. Must be lowercase, use hyphens for word separation, and contain only alphanumeric characters and hyphens. The name must not start or end with a hyphen, and must not contain consecutive hyphens.description(required): A description of what the skill does and when Copilot should use it. This is the most critical field -- it determines whether Copilot activates the skill for a given request.
Optional Frontmatter Fields
---
name: api-test-generator
description: >
Generate comprehensive API integration tests using the project's test framework.
Use for REST API testing, endpoint validation, and contract testing tasks.
license: MIT
---
license(optional): A description of the license that applies to this skill. Useful when sharing skills across organizations or publishing them to the community.
Naming Rules
Valid skill names follow these rules:
| Valid | Invalid | Reason |
|---|---|---|
pdf-processing | PDF-Processing | Must be lowercase |
data-analysis | -pdf | Cannot start with hyphen |
code-review | pdf--processing | No consecutive hyphens |
terraform2 | pdf- | Cannot end with hyphen |
api-test-gen | api test gen | No spaces allowed |
The Markdown Body
The body of SKILL.md contains the instructions that Copilot follows when the skill is activated. This is where you define the step-by-step procedures, constraints, examples, and any other guidance:
---
name: database-migration
description: >
Generate database migration files following project conventions.
Use for schema changes, migrations, rollback scripts, and database tasks.
---
# Database Migration Skill
## Context
This project uses Flyway for database migrations. All migration files
must follow the naming convention `V{version}__{description}.sql`.
## Steps
1. Check the `db/migrations/` directory for the latest version number.
2. Increment the version by 1 for the new migration.
3. Create the migration file with the naming pattern above.
4. Include both the forward migration and a corresponding undo script
in `db/undo/U{version}__{description}.sql`.
5. Validate the SQL syntax by running the project's lint command.
## Constraints
- Never use `DROP TABLE` without explicit user confirmation.
- Always include `IF EXISTS` guards on destructive operations.
- Maximum one schema change per migration file.
## Examples
### Adding a column
```sql
-- V42__add_payment_status_column.sql
ALTER TABLE payments ADD COLUMN status VARCHAR(20) DEFAULT 'pending';
### 2.3 Skill Storage Levels
Skills can be stored at different levels depending on their intended scope.
#### Repository-Level Skills (Project Skills)
Repository-level skills are specific to a single codebase. They live in the repository under the `.github/skills/` directory:
my-repository/ ├── .github/ │ ├── copilot-instructions.md # Custom instructions (always loaded) │ ├── skills/ # Agent skills directory │ │ ├── database-migration/ │ │ │ ├── SKILL.md │ │ │ └── examples/ │ │ │ └── sample-migration.sql │ │ ├── api-test-generator/ │ │ │ ├── SKILL.md │ │ │ └── scripts/ │ │ │ └── validate-openapi.py │ │ └── release-notes/ │ │ └── SKILL.md │ └── agents/ # Custom agents directory │ └── security-reviewer.md ├── src/ └── tests/
For backward compatibility with tools that preceded the open standard, Copilot also reads skills from the `.claude/skills/` directory. If your team has existing skills in that location, Copilot will discover them automatically.
#### Personal Skills
Personal skills are shared across all your projects. They are stored in your home directory:
- **Recommended**: `~/.copilot/skills/<skill-name>/SKILL.md`
- **Legacy/compatible**: `~/.claude/skills/<skill-name>/SKILL.md`
Personal skills are useful for individual developer preferences that span multiple repositories -- for example, a skill that defines how you prefer commit messages to be structured or how you like test files to be organized.
On Windows, the home directory paths translate to:
```powershell
# Windows personal skills location
%USERPROFILE%\.copilot\skills\<skill-name>\SKILL.md
On macOS and Linux:
# macOS/Linux personal skills location
~/.copilot/skills/<skill-name>/SKILL.md
Organization and Enterprise-Level Skills (Roadmap)
As of early 2026, skills can only be created at the repository and personal levels. Support for organization-level and enterprise-level skills is on the GitHub roadmap. When available, organization skills will likely follow the same pattern as organization-level custom agents, which are stored in a .github-private repository accessible across all repositories in the organization.
In the meantime, enterprise teams can achieve a similar effect through the strategies described in Section 2.8 (Enterprise Skill Library Management).
Enterprise Scenario: A large fintech organization with 300 developers anticipates the release of organization-level skills. In preparation, their platform engineering team maintains a central
copilot-skillsrepository containing all approved skills. A GitHub Actions workflow syncs skills from this central repository into the.github/skills/directory of each product repository on a nightly schedule. When organization-level skills become available, they plan to migrate to the native mechanism.
2.4 Skill Anatomy — Components Beyond SKILL.md
A skill directory can contain more than just the SKILL.md file. Copilot can access additional files in the skill directory as needed during task execution. These supporting resources do not load into context automatically -- Copilot references them only when the instructions direct it to do so.
Scripts
Include executable scripts that the agent can run as part of skill execution:
.github/skills/webapp-testing/
├── SKILL.md
└── scripts/
├── check_dependencies.py
└── generate_fixtures.sh
In the SKILL.md, reference the script:
## Steps
1. Run the dependency check script: `python .github/skills/webapp-testing/scripts/check_dependencies.py`
2. If missing dependencies are found, install them before proceeding.
Examples
Provide concrete examples that demonstrate the expected output format:
.github/skills/api-documentation/
├── SKILL.md
└── examples/
├── good-endpoint-doc.md
└── bad-endpoint-doc.md
Templates
Include file templates that the agent should use as starting points:
.github/skills/component-generator/
├── SKILL.md
└── templates/
├── component.tsx.template
├── component.test.tsx.template
└── component.stories.tsx.template
2.5 How Copilot Discovers and Loads Skills
The skill loading process follows a two-phase architecture designed to keep context efficient:
Phase 1 -- Discovery (lightweight):
When you start a conversation or assign a task to the coding agent, Copilot scans all available skill directories and reads only the name and description fields from each SKILL.md frontmatter. This metadata is compact -- typically a few hundred characters per skill -- so even repositories with dozens of skills add minimal overhead.
Phase 2 -- Activation (on demand):
When your request matches a skill's description, Copilot loads the full Markdown body of the relevant SKILL.md into its context. Only at this point do the detailed instructions become available to the agent. Additional files in the skill directory (scripts, examples, templates) are accessed only when the instructions reference them.
This two-phase approach means you can install many skills in a repository without degrading performance. The agent pays the context cost only for skills it actually uses.
Skill Precedence
When the same task matches multiple skills at different levels, Copilot follows a precedence order:
- Repository-level skills (
.github/skills/) -- highest priority - Personal skills (
~/.copilot/skills/) -- lower priority
Repository-level skills take precedence because they represent team-agreed conventions. If a repository-level skill and a personal skill both match a request, the repository-level skill's instructions are used. This ensures that organizational standards override individual preferences when working within a team repository.
2.6 Writing Effective Skills
The quality of a skill depends on two factors: (1) an accurate description that triggers activation at the right time, and (2) clear, structured instructions that the agent can follow deterministically.
Writing Effective Descriptions
The description field is the single most important factor in skill activation. Copilot uses this field to decide whether a skill is relevant to the current request. Follow these patterns:
Pattern 1 -- Task + Keywords:
description: >
Standardize Terraform plan diff reviews. Use for Terraform, plan,
diff, IAM, network, cost, and security review topics.
Pattern 2 -- Problem + Solution:
description: >
Fix failing CI builds by analyzing GitHub Actions workflow logs,
identifying root causes, and suggesting targeted fixes.
Pattern 3 -- Domain + Actions:
description: >
Generate release notes from git history. Categorize changes into
features, fixes, and breaking changes using conventional commits.
Avoid vague descriptions like "Helps with code" or "General development tool." The more specific the description, the more accurately Copilot will activate the skill.
Structuring Skill Instructions
Follow this structure for the Markdown body:
- Context -- What the reader (the agent) needs to know about the project or domain
- Steps -- Numbered, sequential actions the agent should take
- Constraints -- Rules the agent must not violate
- Examples -- Concrete input/output pairs showing the expected behavior
- Error handling -- What to do when things go wrong
---
name: pr-description-generator
description: >
Generate standardized pull request descriptions from commit history
and changed files. Use for PR creation, description writing, and
changelog generation tasks.
---
# PR Description Generator
## Context
This organization requires all pull requests to follow a standard
template that includes a summary, list of changes, testing instructions,
and a risk assessment.
## Steps
1. Read the commit history for the current branch using `git log`.
2. Identify the files changed using `git diff --name-only main...HEAD`.
3. Categorize changes into: features, bug fixes, refactoring, tests,
and documentation.
4. Generate a PR description using the template below.
5. Include a risk assessment based on the files changed.
## Template
Summary
[One paragraph describing the purpose of this PR]
Changes
- Features: [list or "None"]
- Bug Fixes: [list or "None"]
- Refactoring: [list or "None"]
- Tests: [list or "None"]
Testing Instructions
[Step-by-step instructions for reviewers to test the changes]
Risk Assessment
- Risk Level: [Low/Medium/High]
- Affected Systems: [list]
- Rollback Plan: [description]
## Constraints
- Never omit the Risk Assessment section.
- If more than 20 files are changed, flag the PR as "High" risk.
- Always include testing instructions, even if they are "Run the
existing test suite."
## Error Handling
- If the branch has no commits ahead of main, inform the user that
there are no changes to describe.
- If conventional commit format is not used, fall back to file-based
categorization.
Enterprise Scenario: A healthcare SaaS (Software as a Service) company with 200 developers maintains a
pr-description-generatorskill that enforces HIPAA (Health Insurance Portability and Accountability Act) compliance fields in every PR description. The risk assessment section includes mandatory fields for "PHI Data Impact" (Protected Health Information) and "Audit Trail Requirements." When a developer creates a PR that touches database models, the skill automatically classifies it as high-risk and requires a security reviewer to be assigned.
2.7 Testing and Debugging Skills
Unlike application code, skills do not have a formal test framework. However, there are several techniques for validating that skills work correctly.
Validating Frontmatter Syntax
YAML frontmatter must be syntactically correct. Common errors include:
- Missing the opening or closing
---delimiters - Using tabs instead of spaces for indentation
- Forgetting to quote strings that contain colons or special characters
You can validate YAML syntax using standard tools:
# Validate YAML frontmatter using Python (bash)
python3 -c "
import yaml, sys
with open('.github/skills/my-skill/SKILL.md') as f:
content = f.read()
fm = content.split('---')[1]
data = yaml.safe_load(fm)
print('Valid frontmatter:', data)
"
# Validate YAML frontmatter using PowerShell
$content = Get-Content .github/skills/my-skill/SKILL.md -Raw
$frontmatter = ($content -split '---')[1]
# Install powershell-yaml module if not present
# Install-Module -Name powershell-yaml -Scope CurrentUser
$data = ConvertFrom-Yaml $frontmatter
Write-Host "Valid frontmatter:" $data
Testing Activation
To verify that a skill activates for the intended requests, use an iterative approach:
- Create the skill with a clear description.
- Open agent mode in VS Code or use the Copilot CLI.
- Issue a prompt that should trigger the skill.
- Observe whether the agent follows the skill's instructions.
- Refine the description if the skill does not activate or activates for unrelated requests.
Common reasons a skill fails to load:
| Symptom | Likely Cause | Fix |
|---|---|---|
| Skill never activates | Description too vague or does not match prompt keywords | Add specific task keywords to description |
| Skill activates for wrong tasks | Description too broad | Narrow the description to specific task types |
| Skill loads but instructions not followed | Instructions ambiguous or contradictory | Restructure with numbered steps and explicit constraints |
| Skill file not found | Incorrect directory structure or file name | Verify file is named exactly SKILL.md (case-sensitive) |
| Frontmatter parse error | YAML syntax error | Validate with a YAML parser |
Debugging with Verbose Output
In VS Code agent mode, you can observe which skills Copilot loads by reviewing the agent's reasoning in the chat panel. The agent typically mentions which skills it has found and which it is applying. In the Copilot CLI, verbose output may show skill resolution steps.
2.8 Enterprise Skill Library Management
For organizations with 200+ developers, managing skills at scale requires a deliberate strategy.
Centralized Skill Repository
Create a dedicated repository (e.g., my-org/copilot-skills) that serves as the authoritative source for all organization-approved skills:
my-org/copilot-skills/
├── README.md
├── skills/
│ ├── database-migration/
│ │ └── SKILL.md
│ ├── terraform-plan-review/
│ │ └── SKILL.md
│ ├── api-test-generator/
│ │ ├── SKILL.md
│ │ └── scripts/
│ │ └── validate-openapi.py
│ ├── pr-description-generator/
│ │ └── SKILL.md
│ └── incident-response/
│ ├── SKILL.md
│ └── templates/
│ └── incident-report.md
├── CONTRIBUTING.md
└── .github/
└── workflows/
└── distribute-skills.yml
Distributing Skills to Repositories
Until organization-level skills are natively supported, use a GitHub Actions workflow to distribute skills from the central repository to product repositories:
# .github/workflows/distribute-skills.yml
name: Distribute Skills to Repositories
on:
push:
branches: [main]
paths: ['skills/**']
jobs:
distribute:
runs-on: ubuntu-latest
strategy:
matrix:
repo:
- my-org/frontend-app
- my-org/payment-service
- my-org/user-service
- my-org/api-gateway
steps:
- name: Checkout skills repo
uses: actions/checkout@v4
- name: Copy skills to target repository
env:
GH_TOKEN: ${{ secrets.SKILL_DISTRIBUTION_TOKEN }}
run: |
# Clone the target repository
gh repo clone ${{ matrix.repo }} target-repo
cd target-repo
# Create the skills directory if it does not exist
mkdir -p .github/skills
# Copy all skills from the central repository
cp -r ../skills/* .github/skills/
# Commit and push if there are changes
git add .github/skills/
if git diff --staged --quiet; then
echo "No skill changes for ${{ matrix.repo }}"
else
git commit -m "chore: update agent skills from central repository"
git push
fi
Skill Versioning
Although skills do not have a built-in versioning mechanism, enterprise teams can track versions through several approaches:
-
Git tags on the central repository: Tag releases of the skill library (e.g.,
skills-v1.2.0) and reference specific tags in distribution workflows. -
Version comments in SKILL.md: Include a version comment at the top of the Markdown body:
---
name: database-migration
description: Generate database migration files following project conventions.
---
<!-- Skill version: 2.1.0 | Last updated: 2026-01-15 -->
# Database Migration Skill
...
- CHANGELOG in skill directory: Maintain a
CHANGELOG.mdalongside theSKILL.md:
.github/skills/database-migration/
├── SKILL.md
└── CHANGELOG.md
Skill Governance
For large organizations, establish a governance process for skills:
- Skill proposal: Developers submit a PR to the central skills repository with the proposed skill.
- Review: A designated skills team (often a subset of the platform engineering team) reviews the skill for quality, accuracy, and relevance.
- Approval: The skill is merged and distributed to target repositories.
- Maintenance: Skills are reviewed quarterly to ensure they remain accurate as tools and processes evolve.
Enterprise Scenario: An e-commerce company with 400 developers across 12 product teams establishes a "Skills Guild" -- a cross-functional group of senior engineers who meet bi-weekly to review proposed skills, retire outdated ones, and identify gaps in skill coverage. Each product team has a representative in the guild. The guild maintains a catalog of 30+ skills covering everything from React component generation to Kubernetes manifest validation. New developers discover available skills through an internal documentation site that lists all skills with their names, descriptions, and usage examples.
2.9 Skill Discovery and Sharing Across Teams
Making skills discoverable is essential for adoption. Without discovery mechanisms, individual teams build duplicate skills or remain unaware of existing ones.
Internal Skill Catalog
Maintain a catalog (either a markdown file in the skills repository or a page on your internal documentation site) that lists all available skills:
# Copilot Skills Catalog
## Backend Skills
| Skill | Description | Teams Using |
|-------|-------------|-------------|
| `database-migration` | Generate Flyway migration files | Payments, Users, Orders |
| `api-test-generator` | Generate integration tests for REST APIs | All backend teams |
| `grpc-proto-review` | Review Protocol Buffer definitions | Platform, Gateway |
## Frontend Skills
| Skill | Description | Teams Using |
|-------|-------------|-------------|
| `react-component` | Generate React components with tests and stories | Web, Mobile Web |
| `accessibility-audit` | Check components for WCAG 2.1 AA compliance | All frontend teams |
## Infrastructure Skills
| Skill | Description | Teams Using |
|-------|-------------|-------------|
| `terraform-plan-review` | Review Terraform plan diffs | Platform, SRE |
| `k8s-manifest-gen` | Generate Kubernetes manifests from service specs | Platform |
Community Skills
The open skills standard has produced a growing ecosystem of community-created skills. GitHub maintains the github/awesome-copilot repository, which includes a curated collection of skills. Teams can adopt community skills as starting points and customize them for their organization's needs:
# Browse community skills (bash)
gh repo clone github/awesome-copilot
ls awesome-copilot/skills/
3. Diagrams
Skill Resolution Hierarchy
flowchart TD
A[User Request / Coding Agent Task] --> B{Skill Discovery Phase}
B --> C[Scan Repository Skills<br/>.github/skills/*/SKILL.md]
B --> D[Scan Personal Skills<br/>~/.copilot/skills/*/SKILL.md]
B --> E[Scan Legacy Skills<br/>.claude/skills/*/SKILL.md]
C --> F{Read Frontmatter<br/>name + description}
D --> F
E --> F
F --> G{Match Descriptions<br/>Against Request}
G -->|Match Found| H[Load Full SKILL.md Body<br/>into Agent Context]
G -->|No Match| I[Proceed Without Skill]
H --> J{Precedence Resolution}
J -->|Repository-level| K[Use Repository Skill<br/>Highest Priority]
J -->|Personal-level| L[Use Personal Skill<br/>Lower Priority]
K --> M[Execute Task with<br/>Skill Instructions]
L --> M
I --> M
style A fill:#e1f5fe
style K fill:#c8e6c9
style L fill:#fff3e0
style M fill:#e8f5e9
Figure 14.1: Skill resolution hierarchy showing how Copilot discovers skills from multiple storage levels, matches them against the current request using frontmatter metadata, and resolves precedence when multiple skills match. Repository-level skills always take priority over personal-level skills.
Skill Execution Flow
sequenceDiagram
participant U as User / Coding Agent Task
participant C as Copilot Agent
participant S as Skill Registry
participant F as SKILL.md File
participant R as Skill Resources
U->>C: Submit request or assign task
C->>S: Phase 1: Discover available skills
S-->>C: Return list of (name, description) pairs
C->>C: Evaluate descriptions against request
Note over C: Select relevant skills<br/>based on description match
C->>F: Phase 2: Load full SKILL.md body
F-->>C: Return instructions, constraints, steps
C->>C: Follow skill instructions
opt Skill references external files
C->>R: Read scripts/examples/templates
R-->>C: Return file contents
end
C->>C: Execute task following skill steps
C->>U: Return result (PR, code, response)
Figure 14.2: Skill execution flow showing the two-phase loading architecture. In Phase 1, Copilot reads only lightweight metadata. In Phase 2, the full instructions load only for matched skills. Supporting resources (scripts, examples) are accessed on demand.
Skill File Structure
flowchart LR
subgraph Repository[".github/skills/"]
subgraph Skill1["database-migration/"]
A1[SKILL.md<br/>---<br/>name: database-migration<br/>description: ...<br/>---<br/>Instructions...]
A2[examples/<br/>sample-migration.sql]
A3[CHANGELOG.md]
end
subgraph Skill2["api-test-generator/"]
B1[SKILL.md<br/>---<br/>name: api-test-generator<br/>description: ...<br/>---<br/>Instructions...]
B2[scripts/<br/>validate-openapi.py]
B3[examples/<br/>sample-test.py]
end
subgraph Skill3["pr-description/"]
C1[SKILL.md<br/>---<br/>name: pr-description<br/>description: ...<br/>---<br/>Instructions...]
C2[templates/<br/>pr-template.md]
end
end
subgraph CopilotInstructions["Other Customizations"]
D1[.github/copilot-instructions.md<br/>Always loaded - repo norms]
D2[.github/agents/security-reviewer.md<br/>Invoked explicitly]
end
style Repository fill:#e3f2fd
style CopilotInstructions fill:#fce4ec
style Skill1 fill:#e8f5e9
style Skill2 fill:#e8f5e9
style Skill3 fill:#e8f5e9
Figure 14.3: Skill file structure showing the relationship between the .github/skills/ directory (containing multiple skill subdirectories with their SKILL.md files and supporting resources), custom instructions (always loaded), and custom agents (explicitly invoked).
4. Summary
Key Takeaways:
- Agent skills are modular, task-specific knowledge packages defined by
SKILL.mdfiles with YAML frontmatter (nameanddescriptionfields) that Copilot loads on demand -- unlike custom instructions, which are always loaded into context. This selective loading keeps context efficient even in repositories with dozens of skills. - Skills follow a two-phase loading architecture: Phase 1 reads only lightweight metadata (name and description) for all available skills; Phase 2 loads the full instructions only for skills that match the current request. Supporting resources (scripts, examples, templates) in the skill directory are accessed only when referenced.
- Repository-level skills (stored in
.github/skills/) take precedence over personal skills (stored in~/.copilot/skills/). Organization and enterprise-level skills are on the GitHub roadmap. Until then, enterprise teams can use centralized skill repositories with automated distribution workflows to achieve similar effects. - Writing effective skills requires specific, keyword-rich descriptions (the most critical factor in skill activation) and well-structured instructions with numbered steps, explicit constraints, concrete examples, and error handling guidance. Vague descriptions lead to missed activations or false positives.
- Enterprise skill management at scale involves a centralized skill repository with governance processes (proposal, review, approval, maintenance), automated distribution to product repositories via GitHub Actions, version tracking through git tags or comments, and a discoverable catalog that helps teams find and adopt existing skills rather than duplicating effort.
What's Next: See Chapter 15: Working with Agents for how to combine skills with custom agents, MCP servers, and workflow orchestration to build end-to-end agentic development pipelines that handle complex, multi-repository tasks autonomously.
5. Hands-On Assignment
Prerequisites Check: Before starting this lab, ensure you have completed:
- Copilot coding agent enabled and tested (Chapter 13: Copilot Coding Agent — Setup & Operations)
- A repository with GitHub Actions configured (Chapter 12: GitHub Actions & CI/CD Workflows)
Lab: Building a Custom Agent Skill Library
Objective: Create three agent skills for a repository, verify they activate correctly in Copilot agent mode, and establish a skill management structure suitable for enterprise distribution.
Prerequisites:
- A GitHub repository where you have write access (use a test repository if preferred)
- Visual Studio Code with the GitHub Copilot extension (agent mode enabled) or access to the Copilot coding agent
- GitHub Copilot Business or Enterprise subscription (see Chapter 1: Enterprise Subscription & Environment Setup)
- Familiarity with YAML syntax and Markdown formatting
Assignment:
- Create the
.github/skills/directory structure in your repository with three skill subdirectories:code-review-checklist,test-generator, andchangelog-generator. - Write a
SKILL.mdfile for each skill with valid YAML frontmatter (name and description) and a detailed Markdown body containing context, steps, constraints, and at least one example. - For the
test-generatorskill, include a supportingexamples/subdirectory with a sample test file that demonstrates the expected output format. - Test each skill by opening agent mode in VS Code (or assigning a task to the coding agent) and issuing prompts that should trigger each skill. Verify that the agent follows the skill's instructions.
- Validate that a prompt unrelated to any skill (e.g., "What time is it?") does NOT trigger any of your skills.
- Create a
CATALOG.mdfile in the.github/skills/directory that lists all three skills with their names, descriptions, and intended use cases.
Expected Outcome: You should have a .github/skills/ directory containing three fully-defined skills, each with valid frontmatter and structured instructions. The skills should activate correctly for relevant prompts and remain inactive for unrelated ones. A catalog file should provide discoverability for team members.
Validation:
- Each
SKILL.mdfile has valid YAML frontmatter withnameanddescriptionfields - Skill names are lowercase with hyphens (no spaces, no uppercase)
- Each skill's Markdown body contains at least: context, steps, constraints, and one example
- The
test-generatorskill directory contains anexamples/subdirectory with at least one sample file - All three skills activate when relevant prompts are used in agent mode
- The
CATALOG.mdfile accurately lists all three skills
6. Step-by-Step Walkthrough
This section provides a guided solution for the hands-on assignment above. If you completed the assignment independently, you can skip this section or use it to verify your approach.
Step 1: Create the Directory Structure
On macOS/Linux (bash):
# Create the skills directory structure
mkdir -p .github/skills/code-review-checklist
mkdir -p .github/skills/test-generator/examples
mkdir -p .github/skills/changelog-generator
On Windows (PowerShell):
# Create the skills directory structure
New-Item -ItemType Directory -Path .github/skills/code-review-checklist -Force
New-Item -ItemType Directory -Path .github/skills/test-generator/examples -Force
New-Item -ItemType Directory -Path .github/skills/changelog-generator -Force
Verify the structure:
# Verify directory structure (bash)
find .github/skills -type d
# Verify directory structure (PowerShell)
Get-ChildItem .github/skills -Recurse -Directory
Expected output:
.github/skills
.github/skills/changelog-generator
.github/skills/code-review-checklist
.github/skills/test-generator
.github/skills/test-generator/examples
Step 2: Create the Code Review Checklist Skill
Create the file .github/skills/code-review-checklist/SKILL.md with the following content:
---
name: code-review-checklist
description: >
Generate a structured code review checklist based on changed files.
Use for code review, PR review, review checklist, and quality
assurance tasks.
---
# Code Review Checklist Generator
## Context
This project follows enterprise code review standards. Every code
review should cover security, performance, maintainability, and
testing completeness. The checklist adapts based on the types of
files changed.
## Steps
1. Identify all files changed in the current PR or diff.
2. Categorize files by type: source code, tests, configuration,
documentation, CI/CD workflows.
3. Generate a review checklist with the following sections:
- **Security**: Check for hardcoded secrets, SQL injection,
XSS vulnerabilities, and proper input validation.
- **Performance**: Check for N+1 queries, unnecessary loops,
missing indexes, and large payload handling.
- **Maintainability**: Check for proper naming, single
responsibility, documentation, and code duplication.
- **Testing**: Verify test coverage for new code paths, edge
cases, and error handling.
4. Add file-type-specific checks:
- If CI/CD files changed: verify secrets are not exposed,
permissions are minimal.
- If database files changed: verify migration is reversible.
- If API files changed: verify backward compatibility.
5. Output the checklist in Markdown format with checkboxes.
## Constraints
- Always include the Security section regardless of file types.
- Never skip the Testing section, even for documentation changes
(verify docs match actual behavior).
- Flag any file over 500 lines of changes as needing extra review.
## Example Output
```markdown
## Code Review Checklist
### Security
- [ ] No hardcoded secrets or API keys
- [ ] Input validation on all user-facing endpoints
- [ ] SQL queries use parameterized statements
### Performance
- [ ] No N+1 query patterns introduced
- [ ] Pagination used for list endpoints
### Maintainability
- [ ] Functions follow single responsibility principle
- [ ] Public functions have documentation comments
- [ ] No code duplication with existing modules
### Testing
- [ ] Unit tests cover new code paths
- [ ] Edge cases tested (empty input, null values)
- [ ] Error handling paths tested
### Step 3: Create the Test Generator Skill
Create the file `.github/skills/test-generator/SKILL.md`:
```markdown
---
name: test-generator
description: >
Generate unit tests and integration tests following project
conventions. Use for test creation, test generation, unit testing,
integration testing, and test coverage improvement tasks.
---
# Test Generator Skill
## Context
This project uses the following testing conventions:
- Test files are co-located with source files, named
`<filename>.test.<ext>` (e.g., `utils.test.ts`).
- Tests use descriptive `describe` and `it` blocks.
- Each test follows the Arrange-Act-Assert (AAA) pattern.
- Mocks are preferred over real external service calls.
## Steps
1. Identify the source file to be tested.
2. Analyze the file's exports, functions, and classes.
3. For each public function or method:
a. Create a `describe` block named after the function.
b. Write an `it` block for the happy path.
c. Write `it` blocks for edge cases: empty input, null/undefined,
boundary values, error conditions.
d. Write `it` blocks for error handling paths.
4. Use mocks for external dependencies (API calls, database,
file system).
5. Include setup and teardown in `beforeEach`/`afterEach` blocks
if shared state is needed.
6. Verify the test file follows the naming convention.
## Constraints
- Never write tests that depend on network access or external
services without mocking.
- Always include at least one negative test (expected failure case)
per function.
- Do not use `any` type in TypeScript test files.
- Test descriptions must be human-readable sentences.
## Example
See the `examples/` directory for a sample test file that
demonstrates the expected format and patterns.
Now create the example file at .github/skills/test-generator/examples/sample-test.ts:
// examples/sample-test.ts
// Example test file demonstrating project conventions
import { describe, it, expect, beforeEach, vi } from 'vitest';
import { calculateDiscount, validateEmail } from '../utils';
describe('calculateDiscount', () => {
it('should apply percentage discount to the given price', () => {
// Arrange
const price = 100;
const discountPercent = 20;
// Act
const result = calculateDiscount(price, discountPercent);
// Assert
expect(result).toBe(80);
});
it('should return the original price when discount is zero', () => {
const result = calculateDiscount(100, 0);
expect(result).toBe(100);
});
it('should throw an error for negative discount values', () => {
expect(() => calculateDiscount(100, -10)).toThrow(
'Discount cannot be negative'
);
});
it('should handle zero price correctly', () => {
const result = calculateDiscount(0, 50);
expect(result).toBe(0);
});
});
describe('validateEmail', () => {
it('should return true for a valid email address', () => {
expect(validateEmail('user@example.com')).toBe(true);
});
it('should return false for an empty string', () => {
expect(validateEmail('')).toBe(false);
});
it('should return false for a string without @ symbol', () => {
expect(validateEmail('userexample.com')).toBe(false);
});
});
Step 4: Create the Changelog Generator Skill
Create the file .github/skills/changelog-generator/SKILL.md:
---
name: changelog-generator
description: >
Generate changelog entries from git commit history and merged pull
requests. Use for changelog, release notes, version history, and
release documentation tasks.
---
# Changelog Generator Skill
## Context
This project maintains a `CHANGELOG.md` file at the repository root
using the Keep a Changelog format (https://keepachangelog.com). Entries
are categorized under version headings with the following sections:
Added, Changed, Deprecated, Removed, Fixed, Security.
## Steps
1. Determine the version range by identifying the latest tag and
the current HEAD.
2. Retrieve all commits in the range using `git log`.
3. If commits follow Conventional Commits format, categorize them:
- `feat:` → Added
- `fix:` → Fixed
- `refactor:` / `perf:` → Changed
- `deprecate:` → Deprecated
- `revert:` → Removed
- `security:` → Security
4. If commits do not follow Conventional Commits, categorize based
on file paths and commit message keywords.
5. Format the output as a new version section in the changelog.
6. Include PR numbers and author attributions where available.
## Constraints
- Always use ISO 8601 date format (YYYY-MM-DD) for version headings.
- Never remove existing changelog entries; only prepend new ones.
- If no commits match a category, omit that category section.
- Breaking changes must be called out explicitly with a
"BREAKING CHANGE" prefix in the entry.
## Example Output
```markdown
## [1.5.0] - 2026-01-28
### Added
- Add payment retry logic with exponential backoff (#142) - @alice
- Add health check endpoint for load balancer integration (#138) - @bob
### Fixed
- Fix database connection pool exhaustion under high load (#145) - @carol
### Security
- Update dependency `lodash` to patch prototype pollution (#147) - @dave
### Step 5: Test the Skills in Agent Mode
Open VS Code with the GitHub Copilot extension and enable agent mode (or use the Copilot CLI).
**Test the code review checklist skill**:
Issue the following prompt:
Review the changes in my current branch and generate a code review checklist.
Verify that the agent produces a checklist with Security, Performance, Maintainability, and Testing sections as defined in the skill.
**Test the test generator skill**:
Issue the following prompt:
Generate unit tests for the src/utils.ts file following project conventions.
Verify that the agent creates tests using the Arrange-Act-Assert pattern, includes edge cases, and follows the naming convention from the skill.
**Test the changelog generator skill**:
Issue the following prompt:
Generate changelog entries for all commits since the last tag.
Verify that the agent categorizes commits and formats the output in Keep a Changelog format.
**Test negative case -- no skill should activate**:
Issue the following prompt:
What is the capital of France?
Verify that none of your skills activate for this unrelated question.
### Step 6: Create the Skill Catalog
Create the file `.github/skills/CATALOG.md`:
```markdown
# Agent Skills Catalog
This directory contains agent skills that Copilot uses to perform
specialized tasks within this repository.
## Available Skills
| Skill | Name | Description |
|-------|------|-------------|
| Code Review Checklist | `code-review-checklist` | Generates structured code review checklists based on changed files, covering security, performance, maintainability, and testing |
| Test Generator | `test-generator` | Generates unit and integration tests following project conventions with AAA pattern, edge cases, and proper mocking |
| Changelog Generator | `changelog-generator` | Generates changelog entries from git history using Keep a Changelog format with Conventional Commits categorization |
## How Skills Work
Skills are automatically activated by Copilot when your request
matches the skill's description. You do not need to invoke them
manually. See each skill's `SKILL.md` file for detailed instructions
and constraints.
## Contributing
To propose a new skill, create a PR with:
1. A new subdirectory under `.github/skills/` with the skill name
2. A `SKILL.md` file with valid YAML frontmatter
3. Any supporting files (scripts, examples, templates)
Step 7: Commit and Push
# Stage all skill files (bash)
git add .github/skills/
# Commit
git commit -m "feat: add initial agent skills library with three skills"
# Push
git push origin main
# Stage all skill files (PowerShell)
git add .github/skills/
# Commit
git commit -m "feat: add initial agent skills library with three skills"
# Push
git push origin main
Verification
Run the following checks to confirm all lab objectives are met:
# 1. Verify directory structure (bash)
find .github/skills -type f | sort
Expected output:
.github/skills/CATALOG.md
.github/skills/changelog-generator/SKILL.md
.github/skills/code-review-checklist/SKILL.md
.github/skills/test-generator/SKILL.md
.github/skills/test-generator/examples/sample-test.ts
# 2. Verify each SKILL.md has valid frontmatter with name and description (bash)
for skill_dir in .github/skills/*/; do
if [ -f "$skill_dir/SKILL.md" ]; then
echo "=== $skill_dir ==="
head -5 "$skill_dir/SKILL.md"
echo ""
fi
done
# 2. Verify each SKILL.md has valid frontmatter (PowerShell)
Get-ChildItem .github/skills -Directory | ForEach-Object {
$skillFile = Join-Path $_.FullName "SKILL.md"
if (Test-Path $skillFile) {
Write-Host "=== $($_.Name) ==="
Get-Content $skillFile -Head 5
Write-Host ""
}
}
# 3. Verify the test-generator has an examples directory with content (bash)
ls -la .github/skills/test-generator/examples/
# 4. Verify all skill names are lowercase with hyphens only (bash)
ls .github/skills/ | grep -E '^[a-z][a-z0-9-]*$' | wc -l
All checks should pass. You now have a working agent skills library with three skills, supporting resources, and a catalog for team discovery.
7. Q&A -- Chapter Review
Instructions: Select the best answer for each question. Answers and explanations follow after all questions.
Question 1
What is the required filename for a Copilot agent skill definition file?
- A)
skill.yaml - B)
SKILL.md - C)
copilot-skill.md - D)
.skill
Question 2
Which two fields are required in the YAML frontmatter of a SKILL.md file?
- A)
titleanddescription - B)
nameandinstructions - C)
nameanddescription - D)
idandsummary
Question 3
A repository has a skill at .github/skills/api-testing/SKILL.md and a developer has a personal skill at ~/.copilot/skills/api-testing/SKILL.md. Both match the current request. Which skill takes precedence?
- A) The personal skill, because user preferences override repository settings
- B) The repository-level skill, because team conventions take priority
- C) Both are loaded and their instructions are merged
- D) The most recently modified skill takes precedence
Question 4
An enterprise team wants to ensure their database migration skill activates when developers ask about schema changes but NOT when they ask about data analysis. What is the most effective approach?
- A) Set the skill name to
database-migration-only - B) Write a specific description with keywords like "schema changes, migrations, rollback scripts" and avoid generic terms
- C) Add an
excludefield in the frontmatter to block activation for data analysis - D) Place the skill in a special
.github/skills/priority/subdirectory
Question 5
How does Copilot handle scripts and example files stored alongside a SKILL.md in a skill directory?
- A) All files in the directory are loaded into context immediately when the skill activates
- B) Files are loaded only when the skill instructions reference them, keeping context efficient
- C) Only
.mdfiles are accessible; scripts and other files are ignored - D) Files must be registered in the frontmatter using an
includesfield
Question 6
Which naming convention is valid for a Copilot agent skill?
- A)
PDF-Processing - B)
pdf--processing - C)
pdf-processing - D)
-pdf-processing
Question 7
An organization with 300 developers wants to share a standard set of 20 skills across all 150 repositories. Organization-level skills are not yet available. What is the recommended interim approach?
- A) Ask each developer to manually copy skills into their repositories
- B) Maintain a central skills repository and use a GitHub Actions workflow to distribute skills to product repositories
- C) Store all skills as personal skills in each developer's home directory
- D) Embed skill instructions directly in the
.github/copilot-instructions.mdfile
Question 8
What distinguishes agent skills from custom instructions in Copilot?
- A) Skills are always loaded into context; custom instructions are loaded on demand
- B) Custom instructions are always loaded; skills are loaded only when relevant to the current request
- C) Skills require a paid Copilot plan; custom instructions are available on all plans
- D) Custom instructions support scripts and examples; skills support only text
Question 9
A developer creates a skill with the description "Helps with code." When testing, the skill activates for nearly every coding request, including ones it should not handle. What is the root cause?
- A) The skill name is too generic
- B) The description is too vague, causing Copilot to match it against most coding-related requests
- C) The
SKILL.mdfile is in the wrong directory - D) The frontmatter is missing the
scopefield
Question 10
A platform engineering team needs to track which version of a skill is deployed to each repository. Which approach is recommended in the absence of built-in skill versioning?
- A) Use npm to publish skills as packages with semantic versioning
- B) Add version numbers to the skill name (e.g.,
database-migration-v2) - C) Use git tags on the central skills repository and include version comments in the SKILL.md body
- D) Store version information in a separate
.github/skill-versions.jsonfile that Copilot reads automatically
Answer Key
| Q | Answer | Explanation |
|---|---|---|
| 1 | B | Agent skill definition files must be named exactly SKILL.md (uppercase, Markdown format). This is a fixed convention that Copilot uses to discover skills in the directory structure. |
| 2 | C | The name and description fields are the two required frontmatter fields. The name provides a unique lowercase identifier, and the description tells Copilot when to activate the skill. |
| 3 | B | Repository-level skills take precedence over personal skills. This design ensures that team-agreed conventions override individual developer preferences when working in a shared repository. |
| 4 | B | The description field is the primary mechanism for controlling skill activation. Writing specific descriptions with relevant keywords ensures accurate activation. There is no exclude frontmatter field or priority subdirectory mechanism. |
| 5 | B | Copilot accesses additional files in the skill directory only when the instructions reference them. This lazy-loading approach keeps context efficient by avoiding unnecessary content loading. |
| 6 | C | Valid skill names must be lowercase, use hyphens for word separation, and cannot start or end with a hyphen or contain consecutive hyphens. pdf-processing is the only option that meets all these rules. |
| 7 | B | The recommended interim approach is a centralized skills repository with automated distribution via GitHub Actions. This ensures consistency across repositories and provides a clear governance path until native organization-level skills become available. |
| 8 | B | Custom instructions (.github/copilot-instructions.md) are always loaded into the agent's context for every interaction. Agent skills are selectively loaded only when the current request matches the skill's description, making them more efficient for task-specific guidance. |
| 9 | B | A vague description like "Helps with code" matches almost any coding-related request. The fix is to write a specific description with task-oriented keywords that narrow the activation scope to the intended use cases. |
| 10 | C | In the absence of built-in versioning, the recommended approach is to use git tags on the central skills repository for release management and include version comments in the SKILL.md body for traceability at the file level. Changing skill names for versions would break activation, and Copilot does not read a skill-versions.json file. |