Copilot Skill Builder

Skill Builder

This skill helps you create well-structured Agent Skills for GitHub Copilot CLI.

When to use this skill

• User wants to create a new Agent Skill
• User asks about the SKILL.md format or best practices
• User wants to understand how skills work in Copilot CLI
• User needs to debug or improve an existing skill

SKILL.md Format

Every skill lives in its own directory and must contain a SKILL.md file:

.github/skills//
├── SKILL.md          # Required: skill instructions
├── scripts/          # Optional: helper scripts
├── examples/         # Optional: example files
└── templates/        # Optional: template files

SKILL.md Structure

---
name: skill-name
description: What the skill does and when Copilot should use it. Be specific to help Copilot decide when to load this skill.
license: MIT
allowed-tools: read, grep
user-invocable: true
disable-model-invocation: false
---

# Skill Title

Overview of what this skill accomplishes.

## When to use this skill

- Specific trigger 1
- Specific trigger 2

## Step-by-step procedure

1. First step
2. Second step

## Examples

### Example 1: Description
...

## References

- [Link to relevant docs](https://...)

Frontmatter Fields

| Field | Required | Description | |-------|----------|-------------| | name | ✅ Yes | Unique identifier, lowercase with hyphens, max 64 chars | | description | ✅ Yes | What it does and when to use it, max 1024 chars | | license | ❌ No | License information for the skill | | allowed-tools | ❌ No | Comma-separated string or YAML array of tools to allow when active | | user-invocable | ❌ No | Whether users can invoke the skill with /skill-name; defaults to true | | disable-model-invocation | ❌ No | Prevents automatic model invocation; defaults to false |

Skill Locations

| Type | Location | Scope | |------|----------|-------| | Project skills | .github/skills//SKILL.md | Current repository | | Project skills | .agents/skills//SKILL.md | Current repository, cross-agent standard | | Project skills | .claude/skills//SKILL.md | Current repository, Claude-compatible | | Personal skills | ~/.copilot/skills//SKILL.md | All your projects | | Personal skills | ~/.agents/skills//SKILL.md | Shared across agent tools | | Custom locations | COPILOT_SKILLS_DIRS | Additional comma-separated directories | | Plugin skills | /skills//SKILL.md | Installed plugin scope |

Best Practices

Writing effective descriptions

The description field is critical — it's how Copilot decides when to load your skill.

Good descriptions:

• "Guide for debugging failing GitHub Actions workflows. Use when asked to debug CI failures."
• "Convert images between formats using ImageMagick. Use when asked to convert, resize, or optimize images."

Bad descriptions:

• "A useful skill" (too vague)
• "Helps with stuff" (non-specific)

Writing effective instructions

1. Be specific — provide concrete steps, not vague guidance
2. Include examples — show expected input/output pairs
3. Reference resources — link to scripts and files using relative paths (e.g., [template](./template.js))
4. Define scope — clearly state what the skill does and doesn't do
5. Keep it focused — one skill per concern, not a kitchen sink

Including scripts and resources

Skills can include additional files that Copilot can reference:

When creating a new component, use the template at [component-template](./templates/component.tsx)
as a starting point.

To run validation, execute the script at [validate](./scripts/validate.sh).

Only use allowed-tools: shell or allowed-tools: bash for skills and scripts you fully trust. When in doubt, omit shell tools so Copilot asks before running commands.

Managing Skills in Copilot CLI

/skills list     # List available skills
/skills          # Toggle skills on/off interactively
/skills info     # View details about a skill
/skills reload   # Reload after adding new skills
/skills add      # Add alternative skill location
/skills remove   # Remove a skill directory

Skills vs Custom Instructions

| Aspect | Skills | Custom Instructions | |--------|--------|-------------------| | When loaded | On-demand, when relevant | Always, automatically | | Scope | Task-specific | General/project-wide | | Can include scripts | ✅ Yes | ❌ No | | Best for | Detailed task procedures | Coding standards, conventions |

Rule of thumb: Use instructions for "always apply" rules, skills for "when relevant" procedures.

Template

Use [skill-template.md](./skill-template.md) as a starting point for new skills.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: trsdn
• Source: trsdn/github-copilot-cli
• License: MIT

Install and usage instructions live in the source repository linked above.