Understanding Agent Skills

Posted on In ,

Agent Skills are a practical way to package instructions, scripts, and supporting files into a reusable capability. In this post, we use a Copilot agent skill as an example and walk through the file structure, the SKILL.md format, and when to use skills instead of custom instructions.

What Is an Agent Skill

An agent skill is a folder of reusable guidance that an AI agent can load when a task matches the skill’s purpose. Instead of repeating the same steps in every conversation, you can capture the workflow once and let the agent reuse it on demand.

The main benefit is portability. A well-structured skill can work across different Copilot surfaces and other skill-compatible agents, so the same workflow does not have to be rewritten for every tool.

Skills vs Custom Instructions

Agent skills and custom instructions solve different problems.

Custom instructions are best for stable coding preferences, project conventions, and always-on rules. Agent skills are better for task-specific capabilities such as debugging, testing, deployment, or generating reports.

Use a skill when you need:

  • A repeatable workflow with multiple steps
  • Scripts, templates, or example files alongside instructions
  • A capability that should load only when relevant
  • A reusable package that can travel between agents

Use custom instructions when you need:

  • Language or framework conventions
  • Team-wide coding style rules
  • Persistent project preferences that should always apply

Skill File Structure

A skill is stored in a directory that contains a SKILL.md file. For a project skill, the common layout looks like this:

1
2
3
4
5
6
7
extension-root/
└── skills/
    └── my-skill/
        ├── SKILL.md
        ├── helper-script.sh
        └── examples/
            └── sample-input.md

The important rule is that the directory name must match the name field inside SKILL.md. If the folder is my-skill, then the frontmatter name must also be my-skill.

When a skill is contributed by an extension, the structure is similar but the path is registered from package.json:

1
2
3
4
extension-root/
└── skills/
    └── my-skill/
        └── SKILL.md
1
2
3
4
5
6
7
8
9
{
  "contributes": {
    "chatSkills": [
      {
        "path": "./skills/my-skill/SKILL.md"
      }
    ]
  }
}

SKILL.md Anatomy

SKILL.md has two parts: YAML frontmatter at the top and the instruction body below it.

The frontmatter is where you define metadata that helps the agent discover and load the skill:

1
2
3
4
5
6
7
8
---
name: my-skill
description: Explain what this skill does and when to use it.
argument-hint: [file] [options]
user-invocable: true
disable-model-invocation: false
context: inline
---

The most important fields are:

  • name - unique skill identifier, using lowercase letters, numbers, and hyphens only
  • description - what the skill does and when it should be loaded
  • argument-hint - optional hint shown when the skill is used as a slash command
  • user-invocable - whether the skill appears in the chat menu
  • disable-model-invocation - whether the model can load it automatically
  • context - whether the skill runs inline or in a forked context

The body of the file should describe the workflow clearly and specifically. A good skill usually includes:

  • What the skill helps accomplish
  • When to use it
  • Step-by-step instructions
  • Expected input and output
  • Links to any helper scripts or example files

A More Realistic Example

Here is a practical example of a skill for explaining code clearly and consistently:

1
2
3
4
5
code-explainer/
├── SKILL.md          # Required: metadata + instructions
├── examples/         # Optional: sample snippets and outputs
├── references/       # Optional: supporting notes and references
└── ...               # Any additional files or directories
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
---
name: code-explainer
description: Use this skill when the user explicitly asks to explain a snippet of code, a file, or a function.
---

# Code Explainer Skill

You are an expert software engineering instructor. Your goal is to break down complex code into simple, universally accessible explanations for developers of all levels.

## 🚀 Execution Steps

1. **Analyze the Code**: Read the provided snippet or file thoroughly. Identify the programming language, core logic, and dependencies.
2. **High-Level Summary**: Write a single-sentence overview explaining *what* the code does in plain English.
3. **Step-by-Step Breakdown**: Divide the code into logical blocks. Explain *how* each block works using bullet points.
4. **Key Concept Highlight**: Call out any specific design patterns, algorithms, or complex built-in functions used.
5. **Time & Space Complexity**: Provide a brief Big O notation estimation for execution speed and memory usage.

## 📝 Output Template
Format your final response strictly using this structure:

### 🎯 Overview
[One sentence high-level summary]

### 🔍 Step-by-Step Breakdown
- **[Line numbers/Block name]**: [Explanation]
- **[Line numbers/Block name]**: [Explanation]

### 💡 Key Concepts
- **[Concept Name]**: [Brief educational note]

### 📊 Complexity
- **Time Complexity**: `O(?)` because...
- **Space Complexity**: `O(?)` because...

This layout makes the skill easier to understand because the main instructions stay in SKILL.md, while supporting material is organized into predictable folders.

Practical Guidance

If you are designing a skill for your own workflow, keep it narrow. A skill works best when it solves one recognizable task well instead of trying to become a catch-all handbook.

I also recommend writing the description as if it were a search query. The better the description matches the user’s intent, the more reliably the agent can decide when to load the skill.

Recommended Skills

Conclusion

Agent skills are a clean way to turn repeated AI workflows into reusable capabilities. For Copilot agent skill work, the key pieces are the directory structure, the SKILL.md frontmatter, and clear instructions in the body. Once those are in place, the same skill can be reused across tasks without repeating the setup every time.