Creating agent skills for GitHub Copilot-CLI

Modify Copilot's behavior and abilities when it works on particular tasks.

In diesem Artikel

Agent skills are folders of instructions, scripts, and resources that Copilot can load when relevant to improve its performance in specialized tasks. For more information, see Informationen zu Agentenkenntnissen.

Creating and adding a skill

To create an agent skill you write a SKILL.md file and, optionally, other resources, such as supplementary Markdown files, or scripts, which you reference in the SKILL.md instructions.

To add a skill, you save the SKILL.md file, and any subsidiary resources, to a location where Copilot knows to look for skills. This can be within a repository, or within your home directory.

  1. Create a skills directory to store your skill and any others you may want to create in the future.

    For project skills, specific to a single repository, store your skill under .github/skills or .claude/skills.

    For personal skills, shared across projects, store your skill under ~/.copilot/skills or ~/.claude/skills.

  2. Create a subdirectory for your new skill. Each skill should have its own directory (for example, .github/skills/webapp-testing).

    Skill subdirectory names should be lowercase and use hyphens for spaces.

  3. In your skill subdirectory, create a SKILL.md file containing your skill's instructions.

    Wichtig

    Skill files must be named SKILL.md.

    SKILL.md files are Markdown files with YAML frontmatter. In their simplest form, they include:

    • YAML frontmatter
      • name (required): A unique identifier for the skill. This must be lowercase, using hyphens for spaces. Typically, this matches the name of the skill's directory.
      • description (required): A description of what the skill does, and when Copilot should use it.
      • license (optional): A description of the license that applies to this skill.
    • A Markdown body, with the instructions, examples and guidelines for Copilot to follow.

  4. Optionally, add scripts, examples or other resources to your skill's directory.

    For example, if you were writing a skill for converting images between different formats, you might include a script for converting SVG images to PNG. The skill instructions should tell Copilot when, and how, to use these resources.

Example SKILL.md file

For a project skill, this file would be located in a .github/skills/github-actions-failure-debugging directory of your repository.

For a personal skill, this file would be located in a ~/.copilot/skills/github-actions-failure-debugging directory.

Markdown
---
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 in a pull request, follow this process, using tools provided from the GitHub MCP Server:

1. Use the `list_workflow_runs` tool to look up recent workflow runs for the pull request and their status
2. Use the `summarize_job_log_failures` tool to get an AI summary of the logs for failed jobs, to understand what went wrong without filling your context windows with thousands of lines of logs
3. If you still need more information, use the `get_job_logs` or `get_workflow_run_logs` tool to get the full, detailed failure logs
4. Try to reproduce the failure yourself in your own environment.
5. Fix the failing build. If you were able to reproduce the failure yourself, make sure it is fixed before committing your changes.

Using agent skills

When performing tasks, Copilot will decide when to use your skills based on your prompt and the skill's description.

When Copilot chooses to use a skill, the SKILL.md file will be injected in the agent's context, giving the agent access to your instructions. It can then follow those instructions and use any scripts or examples you may have included in the skill's directory.

To tell Copilot to use a specific skill, include the skill name in your prompt, preceded by a forward slash. For example, if you have a skill named "frontend-design" you could use a prompt such as:

Use the /frontend-design skill to create a responsive navigation bar in React.

Skills commands in the CLI

  • List the currently available skills: use the command /skills list or the prompt:

    What skills do you have?

  • Enable or disable specific skills: use the command /skills and then use the up and down keys on your keyboard, and the space bar, to toggle skills on or off.

  • Find out more about a skill (including its location): use the command /skills info.

  • Add a skills location: to add an alternative location in which to store skills, use the command /skills add.

  • Reload skills: if you have added a skill during a CLI session, you can add it using the command /skills reload to avoid having to restart the CLI to use it.

  • Remove skills: to remove a skill that you have added directly—not via a plugin—use the command /skills remove SKILL-DIRECTORY. To remove skills added as part of a plugin you must manage the plugin itself. Use the info subcommand to find out which plugin a skill came from.

Skills versus custom instructions

You can use both skills and custom instructions to teach Copilot how to work in your repository and how to perform specific tasks.

We recommend using custom instructions for simple instructions relevant to almost every task (for example information about your repository's coding standards), and skills for more detailed instructions that Copilot should only access when relevant.

To learn more about repository custom instructions, see Hinzufügen benutzerdefinierter Repositoryanweisungen für GitHub Copilot.

To learn more about how skills differ from other customization features, see Comparing GitHub Copilot CLI customization features.