awesome-copilot/website/src/content/docs/learning-hub/creating-effective-skills.md

title, description, authors, lastUpdated, estimatedReadingTime, tags, relatedArticles, prerequisites

title	description	authors	lastUpdated	estimatedReadingTime	tags	relatedArticles	prerequisites
Creating Effective Skills	Master the art of writing reusable, shareable skill folders that deliver consistent results across your team.	GitHub Copilot Learning Hub Team	2026-07-11	9 minutes	skills customization fundamentals	./what-are-agents-skills-instructions.md ./defining-custom-instructions.md	Basic understanding of GitHub Copilot chat

Skills are self-contained folders that package reusable capabilities—instructions, reference files, templates, and scripts—into a single unit that agents can discover automatically and users can invoke via slash commands. They enable teams to standardize common workflows like generating tests, reviewing code, or creating documentation, ensuring consistent, high-quality results across all team members.

This article shows you how to design, structure, and optimize skills that solve real development challenges.

What Are Skills?

Skills are folders containing a SKILL.md file and optional bundled assets. The SKILL.md defines:

• Name: A kebab-case identifier that doubles as the /command users invoke (e.g., /generate-tests)
• Description: What the skill accomplishes and when it should be triggered
• Instructions: The detailed workflow Copilot executes
• Asset references: Links to bundled templates, scripts, schemas, and reference documents

Key advantages over the older prompt file format:

• Skills support extended frontmatter for agent discovery—agents can find and invoke skills automatically, while prompts required manual slash-command invocation
• Skills can bundle additional files (reference docs, templates, scripts) alongside their instructions, giving the AI richer context
• Skills are more normalised across coding agent systems via the open Agent Skills specification
• Skills still support slash-command invocation just like prompts did

How Skills Differ from Other Customizations

Skills vs Instructions:

• Skills are invoked explicitly (by agents or users); instructions apply automatically
• Skills drive specific tasks with bundled resources; instructions provide ongoing context
• Use skills for workflows you trigger on demand; use instructions for standards that always apply

Skills vs Agents:

• Skills are task-focused capabilities; agents are specialized personas
• Skills work with standard Copilot tools and bundle their own assets; agents may require MCP servers or custom integrations
• Use skills for repeatable tasks; use agents for complex multi-step workflows that need persistent state

Anatomy of a Skill

Every effective skill has two parts: a SKILL.md file with frontmatter and instructions, plus optional bundled assets.

SKILL.md Structure

Example - Simple Skill (skills/generate-tests/SKILL.md):

---
name: generate-tests
description: 'Generate comprehensive unit tests for the selected code, covering happy path, edge cases, and error conditions'
---

# generate-tests

Generate comprehensive unit tests for the selected code.

## When to Use This Skill

Use this skill when you need to create or expand test coverage for existing code.

## Requirements

- Cover happy path, edge cases, and error conditions
- Use the testing framework already present in the codebase
- Follow existing test file naming conventions
- Include descriptive test names explaining what is being tested
- Add assertions for all expected behaviors

Why This Works:

• Clear name field provides the slash-command identifier
• Rich description tells agents when to invoke this skill
• Structured instructions provide specific, actionable guidance
• Generic enough to work across different projects

Adding Bundled Assets

Skills can include reference files, templates, and scripts that enrich the AI's context:

skills/
└── generate-tests/
    ├── SKILL.md
    ├── references/
    │   └── testing-patterns.md      # Common testing patterns
    ├── templates/
    │   └── test-template.ts         # Starter test file
    └── scripts/
        └── setup-test-env.sh        # Environment setup

Reference these assets in your SKILL.md instructions:

## Testing Patterns

Follow the patterns documented in [references/testing-patterns.md](references/testing-patterns.md).

Use [templates/test-template.ts](templates/test-template.ts) as a starting structure.

Frontmatter Configuration

The YAML frontmatter controls how Copilot discovers and executes your skill.

Required Fields

name: Kebab-case identifier matching the folder name

name: generate-tests

description: Brief summary of what the skill does and when to use it (10–1024 characters, wrapped in single quotes)

description: 'Generate comprehensive unit tests for a component, covering happy path, edge cases, and error conditions'

Description Best Practices

The description field is critical for agent discovery. Write it so that agents understand when to invoke the skill:

✅ Good: 'Generate conventional commit messages by analyzing staged git changes and applying the Conventional Commits specification'

❌ Poor: 'Commit helper'

Include trigger keywords and contextual cues that help agents match the skill to user intent.

Optional Fields

argument-hint (v1.0.64+): A short label that appears in the slash-command input placeholder to guide the user on what argument to provide. For example, a generate-tests skill might set:

argument-hint: 'Enter function or file to test'

When the user types /generate-tests in VS Code Chat, the hint appears as placeholder text in the input box, making the expected input immediately obvious.

---
name: generate-tests
description: 'Generate comprehensive unit tests for the selected code, covering happy path, edge cases, and error conditions'
argument-hint: 'Enter function, class, or file to test'
---

Real Examples from the Repository

The awesome-copilot repository includes skill folders demonstrating production patterns.

Conventional Commits

See skills/conventional-commit/SKILL.md for automating commit messages:

---
name: conventional-commit
description: 'Generate conventional commit messages from staged changes following the Conventional Commits specification'
---

# conventional-commit

## Workflow

Follow these steps:

1. Run `git status` to review changed files
2. Run `git diff --cached` to inspect changes
3. Construct commit message using Conventional Commits format
4. Execute commit command automatically

## Commit Message Structure

<type>(scope): description

Types: feat|fix|docs|style|refactor|perf|test|build|ci|chore

## Examples

- feat(parser): add ability to parse arrays
- fix(ui): correct button alignment
- docs: update README with usage instructions

This skill automates a repetitive task (writing commit messages) with a proven template that agents can discover and invoke automatically.

Diagram Generation with Bundled Assets

See skills/excalidraw-diagram-generator/ for a skill with rich bundled resources:

excalidraw-diagram-generator/
├── SKILL.md
├── references/
│   ├── excalidraw-schema.md
│   └── element-types.md
├── templates/
│   ├── flowchart-template.json
│   └── relationship-template.json
└── scripts/
    └── split-excalidraw-library.py

This skill packages schema documentation, starter templates, and utility scripts so the AI has everything it needs to generate valid diagrams without hallucinating the format.

Writing Effective Skill Instructions

Structure Your Skills

1. Start with clear objectives:

# skill-name

Your goal is to [specific task] for [specific target].

2. Add "When to Use" guidance (helps agent discovery):

## When to Use This Skill

Use this skill when:
- A user asks to [trigger phrase 1]
- You need to [trigger phrase 2]
- Keywords: [keyword1], [keyword2], [keyword3]

3. Define requirements explicitly:

## Requirements

- Must follow [standard/pattern]
- Should include [specific element]
- Avoid [anti-pattern]

4. Reference bundled assets:

## References

- Follow patterns in [references/patterns.md](references/patterns.md)
- Use template from [templates/starter.json](templates/starter.json)

5. Provide examples:

### Good Example
[Show desired output]

### What to Avoid
[Show problematic patterns]

Best Practices

• One purpose per skill: Focus on a single task or workflow
• Write for discovery: Craft descriptions with trigger keywords so agents find the right skill
• Bundle what matters: Include templates, schemas, and reference docs that reduce hallucination
• Make it generic: Write skills that work across different projects
• Be explicit: Avoid ambiguous language; specify exact requirements
• Name descriptively: Use clear, action-oriented names: generate-tests, not helper
• Keep assets lean: Bundled files should be under 5 MB each
• Test thoroughly: Verify skills work with different inputs and codebases

Writing Style Guidelines

Use imperative mood:

• ✅ "Generate unit tests for the selected function"
• ❌ "You should generate some tests"

Be specific about requirements:

• ✅ "Use Jest with React Testing Library"
• ❌ "Use whatever testing framework"

Provide guardrails:

• ✅ "Do not modify existing test files; create new ones"
• ❌ "Update tests as needed"

Structure complex skills:

## Step 1: Analysis
[Analyze requirements]

## Step 2: Generation
[Generate code]

## Step 3: Validation
[Check output]

Common Patterns

Multi-Step Workflow with References

---
name: scaffold-feature
description: 'Scaffold a new feature with implementation, tests, and documentation following project conventions'
---

# scaffold-feature

Create a complete feature implementation:

1. **Analyze**: Review existing patterns in codebase
2. **Generate**: Create implementation files following project structure
3. **Test**: Generate comprehensive test coverage using [references/test-patterns.md](references/test-patterns.md)
4. **Document**: Add inline comments and update relevant docs
5. **Validate**: Check for common issues and anti-patterns

Use the existing code style and conventions found in the codebase.

Quick Analysis Skill

---
name: explain-architecture
description: 'Analyze and explain code architecture, design patterns, and data flow for selected code'
---

# explain-architecture

Analyze the selected code and explain:

1. Overall architecture and design patterns used
2. Key components and their responsibilities
3. Data flow and dependencies
4. Potential improvements or concerns

Keep explanations concise and developer-focused.

Skill with Script Assets

---
name: run-test-suite
description: 'Execute the project test suite, parse failures, and suggest fixes for failing tests'
---

# run-test-suite

Execute the project's test suite:

1. Identify the test command from package.json or build files
2. Run tests in the integrated terminal
3. Parse test output for failures
4. Summarize failed tests with relevant file locations
5. Suggest potential fixes based on error messages

Use [scripts/parse-test-output.sh](scripts/parse-test-output.sh) to extract structured failure data.

Common Questions

Q: How do I invoke a skill?

A: Skills can be invoked in several ways:

• Slash command: Type the skill name anywhere in your message (e.g., /generate-tests fix the failing tests). Since v1.0.44, slash commands can appear mid-input — you don't have to start with them.
• Multiple skills in one message: You can invoke multiple skills in a single message (e.g., /generate-tests and then /conventional-commit). Both skills will be executed in sequence.
• Agent discovery: Agents can also discover and invoke skills automatically based on the skill's description and the user's intent — no slash command required.

Q: How do I manage skills from the CLI?

A: The copilot skill subcommand (v1.0.65+) lets you list, add, and remove skills directly from the terminal without editing config files manually:

copilot skill list                      # list all currently loaded skills
copilot skill add ./my-skill/           # add a skill from a local directory
copilot skill add https://example.com/skill.zip  # add a skill from a URL
copilot skill remove my-skill           # remove an installed skill by name

You can also run /skill (or the existing /skills) inside an interactive session to see what's loaded. The copilot skill subcommand is the recommended way to install skills that aren't packaged inside a plugin.

Q: How are skills different from prompts?

A: Skills replace the older prompt file (*.prompt.md) format. Skills offer agent discovery (prompts were manual-only), bundled assets (prompts were single files), and cross-platform portability via the Agent Skills specification. If you have existing prompts, consider migrating them to skills.

Q: Can skills include multiple files?

A: Yes! Skills are folders, not single files. You can bundle reference documents, templates, scripts, and any other resources the AI needs. Keep individual assets under 5 MB.

Q: How do I share skills with my team?

A: Store skill folders in your repository's .github/skills/ directory. They're automatically available to all team members with Copilot access when working in that repository.

Q: Can I invoke multiple skills in one message?

A: Yes, since v1.0.44. You can include multiple slash commands in a single message (e.g., /generate-tests and then /conventional-commit), and the CLI will execute each skill in sequence. Agents can also discover and chain multiple skills during a conversation based on user intent. Each skill invocation is independent, but agents maintain conversation context across invocations.

Q: Should skills include code examples?

A: Yes, for clarity. Show examples of desired output format, patterns to follow, or anti-patterns to avoid. For complex schemas or formats, consider bundling them as reference files rather than inline examples.

Q: How do I review agent-proposed skill changes?

A: In v1.0.66+, the agent can propose draft skill additions or improvements as it discovers reusable patterns during a session. Review each draft interactively with:

/chronicle skills review

This opens a review flow where you can accept, reject, or defer each proposed change — giving you full control over how your skill library evolves. No changes are applied until you approve them.

Q: What is Forge and how does it create skills automatically?

A: In v1.0.70+, Forge is the CLI's workflow pattern detector. When the CLI observes that you or an agent are repeatedly following a clear workflow pattern — a sequence of steps that keeps recurring across prompts — it automatically creates a draft skill capturing that pattern. You then review and approve it with /chronicle skills review before it is saved. This makes growing your skill library feel organic: instead of manually authoring skills from scratch, Forge surfaces them from work you are already doing.

Common Pitfalls to Avoid

• ❌ Vague description: "Code helper" doesn't help agents discover the skill ✅ Instead: Write descriptions with trigger keywords: "Generate comprehensive unit tests covering happy path, edge cases, and error conditions"

• ❌ Missing bundled resources: Expecting the AI to know your test patterns or schemas ✅ Instead: Bundle reference docs and templates in the skill folder

• ❌ Too many responsibilities: A skill that generates, tests, documents, and deploys ✅ Instead: Create focused skills for each concern

• ❌ Hardcoded paths: Referencing specific project file paths in skill instructions ✅ Instead: Write generic instructions that work across projects

• ❌ No examples: Abstract requirements without concrete guidance ✅ Instead: Include "Good Example" and "What to Avoid" sections, or bundle templates

Next Steps

Now that you understand effective skills, you can:

• Explore Repository Examples: Browse the Skills Directory for production skills covering diverse workflows
• Learn About Agents: Building Custom Agents — When to upgrade from skills to full agents
• Understand Instructions: Defining Custom Instructions — Complement skills with automatic context
• Decision Framework: Choosing the Right Customization (coming soon) — When to use skills vs other types

Suggested Reading Order:

1. This article (creating effective skills)
2. Building Custom Agents — More sophisticated workflows
3. Choosing the Right Customization (coming soon) — Decision guidance

---