GitHub Copilot CLI Skills: Create, Add, and Use Them Step by Step

If you use GitHub Copilot CLI often, skills are one of the best ways to make it more useful for repeated workflows. A skill lets you teach Copilot how to handle a specific kind of task by giving it focused instructions, examples, and optional helper scripts.

This guide walks through the full process of creating a skill, adding it to GitHub Copilot CLI, reloading it, checking that it works, and using it in real prompts.

What a skill is

A skill is a folder that contains:

• a required SKILL.md file
• optional helper files such as scripts, examples, or reference documents

When Copilot decides a skill is relevant, it loads that skill's instructions into context and uses them while working on your task.

Skills are best for:

• debugging a recurring problem type
• standardizing how Copilot performs a workflow
• teaching Copilot project-specific procedures
• packaging reusable scripts or checklists with instructions

If you want behavior that applies to almost every task, use custom instructions instead. If you want behavior that only matters for a specialized task, use a skill.

Where skills can live

You can create skills at either the personal level or the project level.

Personal skills

These work across many projects. Valid personal skills directories include:

• ~/.copilot/skills
• ~/.claude/skills
• ~/.agents/skills

On Windows, ~/.copilot/skills usually maps to something like:

C:\Users\YOUR_USERNAME\.copilot\skills

Example:

C:\Users\Saeed\.copilot\skills

Project skills

These only apply to one repository. Valid project skills directories include:

• .github/skills
• .claude/skills
• .agents/skills

Example:

my-project\.github\skills

Skill folder structure

Each skill must live in its own folder, and the folder should use lowercase letters with hyphens.

Example:

.github\skills\github-actions-failure-debugging

Inside that folder, you must create a file named exactly:

SKILL.md

That filename is required. If the file is named anything else, Copilot will not load it as a skill.

Step 1: Create the skill folder

Choose whether the skill should be personal or project-specific, then create a new folder for it.

Example personal skill path:

C:\Users\Saeed\.copilot\skills\github-actions-failure-debugging

Example project skill path:

my-project\.github\skills\github-actions-failure-debugging

Step 2: Create SKILL.md

Your SKILL.md file uses Markdown with YAML frontmatter at the top.

At minimum, it should contain:

• name - required
• description - required
• license - optional

Minimal example

---
name: github-actions-failure-debugging
description: Guide for debugging failing GitHub Actions workflows. Use this when asked to debug failing GitHub Actions workflows.
---

To debug failing GitHub Actions workflows, follow this process:

1. Check recent workflow runs and identify the failed jobs.
2. Read failure summaries first before pulling full logs.
3. Reproduce the issue locally when possible.
4. Fix the issue and confirm the failure is resolved.

Important naming rules

• name should be lowercase
• use hyphens instead of spaces
• the name should be unique
• the directory name usually matches the skill name

Step 3: Write useful instructions

The body of SKILL.md is where you teach Copilot how to behave.

Good skill instructions usually include:

• when the skill should be used
• the exact process Copilot should follow
• preferred tools or commands
• constraints and warnings
• examples of good outcomes

Better example

---
name: api-bug-triage
description: Helps investigate and fix backend API bugs. Use this when asked to debug failing API routes, server errors, or incorrect API responses.
---

Use this skill when the task is about diagnosing or fixing API behavior.

Follow this process:

1. Identify the failing route, endpoint, or request path.
2. Inspect the handler, validation, service, and data-access layers involved.
3. Reproduce the issue locally if possible.
4. Look for recent code changes or mismatched assumptions in request and response shapes.
5. Prefer fixing the root cause instead of adding defensive workarounds.
6. After making changes, run the project's existing checks relevant to the affected area.

When reporting the result:

- state the root cause clearly
- describe the fix briefly
- mention any assumptions or remaining edge cases

This is much more helpful than a short generic paragraph because it tells Copilot exactly how to approach the work.

Step 4: Add optional supporting files

You can include extra files in the same skill folder, such as:

• shell scripts
• PowerShell scripts
• example inputs
• checklists
• reference Markdown files

Example:

.github\skills\image-convert\
├── SKILL.md
├── convert-svg-to-png.sh
└── examples.md

When the skill is invoked, Copilot can discover these files and use them along with the skill instructions.

Step 5: Let a skill use a script

If your skill depends on a script, place the script in the skill folder and tell Copilot exactly how to use it.

Example SKILL.md:

---
name: image-convert
description: Converts SVG images to PNG format. Use this when asked to convert SVG files.
---

When asked to convert an SVG to PNG, run the `convert-svg-to-png.sh` script
from this skill's base directory and pass the input SVG path as the first argument.

This works best when your instructions are explicit about:

• which script to run
• where it is located
• what arguments it expects
• what output should be produced

Step 6: Optionally pre-approve tools

You can add an allowed-tools field in the frontmatter so Copilot can use specific tools without asking every time.

Example:

---
name: image-convert
description: Converts SVG images to PNG format. Use this when asked to convert SVG files.
allowed-tools: shell
---

Be careful with this.

Pre-approving shell or bash can be risky because it removes an approval step before terminal commands run. Only do this if you fully trust the skill and any scripts it references.

If you are unsure, leave allowed-tools out and let Copilot ask before running commands.

Step 7: Add the skill to Copilot CLI

Once the skill folder exists in one of the supported locations, Copilot CLI can load it.

If you add the skill while the CLI is already running, reload skills with:

/skills reload

If you are starting a fresh session, simply launching Copilot again is often enough because it will load available skills at startup.

Step 8: Verify the skill is available

Use these commands inside Copilot CLI:

List skills

/skills list

This shows the currently available skills.

Get info about one skill

/skills info github-actions-failure-debugging

This helps confirm:

• the skill was detected
• the loaded skill name is correct
• where Copilot found it

Enable or disable skills interactively

/skills

This opens the skills manager where you can toggle skills on or off.

Add another skill location

/skills add

Use this if you want Copilot to load skills from an additional directory.

Remove a skill location or installed skill

/skills remove SKILL-DIRECTORY

Use /skills info first if you are not sure where a skill came from.

Step 9: Use the skill

There are two main ways to use a skill.

1. Let Copilot choose it automatically

If the skill description clearly matches your task, Copilot may decide to use it automatically.

For example, if your skill description says it is for debugging failing GitHub Actions workflows, then prompts about broken CI jobs may trigger it.

2. Call the skill explicitly in your prompt

You can directly reference the skill name with a leading slash:

Use the /github-actions-failure-debugging skill to investigate why this workflow is failing.

Another example:

Use the /api-bug-triage skill to debug the 500 error in this Express route.

This is the most reliable way to force a specific skill into the workflow.

Example: full skill from start to finish

Here is a complete example of a practical skill.

Folder:

C:\Users\Saeed\.copilot\skills\frontend-design

File:

C:\Users\Saeed\.copilot\skills\frontend-design\SKILL.md

Contents:

---
name: frontend-design
description: Helps design and refine frontend UI components. Use this when asked to improve layout, spacing, responsiveness, or visual hierarchy in web interfaces.
---

Use this skill for frontend UI and UX refinement tasks.

Follow this process:

1. Identify the page, component, or layout being changed.
2. Understand the current structure before changing styles.
3. Prefer small, coherent improvements over broad rewrites.
4. Preserve accessibility and responsive behavior.
5. Reuse existing component patterns when possible.

When making changes:

- improve spacing and alignment
- make responsive behavior explicit
- preserve semantic HTML
- avoid introducing inconsistent styles

When reporting back:

- explain the main visual improvement
- mention any responsive or accessibility impact

Then in Copilot CLI:

/skills reload
/skills info frontend-design

And then use it like this:

Use the /frontend-design skill to improve the layout of the homepage hero section.

When to use skills vs custom instructions

Use skills when:

• the guidance is specialized
• it only applies to some tasks
• the workflow benefits from step-by-step instructions
• you want to bundle scripts or reference files with the instructions

Use custom instructions when:

• the guidance should apply to almost every task
• you want repository-wide conventions
• you are defining coding style, architecture preferences, or team norms

In short:

• custom instructions shape general behavior
• skills teach targeted workflows

Common mistakes

1. Naming the file incorrectly

The file must be named exactly SKILL.md.

2. Putting the skill in the wrong directory

The skill folder must be inside one of the supported skills directories.

3. Writing a vague description

If the description is too generic, Copilot may not know when to use the skill.

Bad example:

description: Helps with coding.

Better example:

description: Helps debug failing GitHub Actions workflows. Use this when asked to investigate CI failures, broken workflow jobs, or failing pull request checks.

4. Giving weak instructions

If the body of the skill is too short or abstract, the skill will not add much value.

5. Forgetting to reload skills

If you add or change a skill during an active session, run:

/skills reload

Recommended workflow

If you are creating a skill for the first time, this is a good process:

1. Start with one narrow use case.
2. Write a very clear description that explains when the skill should be used.
3. Add a short but precise step-by-step process.
4. Reload the skills in Copilot CLI.
5. Check the skill with /skills info.
6. Invoke it explicitly with /skill-name.
7. Improve the instructions after seeing how Copilot uses it in practice.

Useful CLI commands summary

/skills
/skills list
/skills info SKILL-NAME
/skills add
/skills reload
/skills remove SKILL-DIRECTORY

Final thoughts

Skills are a practical way to make GitHub Copilot CLI better at your own workflows. A good skill is not just a note or a label. It is a small, focused operating guide that tells Copilot when to act, how to act, and what good output looks like.

Start simple. Build one skill for a workflow you repeat often. Once that works well, create more skills for the other tasks where you want Copilot to behave consistently and intelligently.