mirror of
https://github.com/github/awesome-copilot.git
synced 2026-03-12 04:05:12 +00:00
docs: replace prompts with skills across Learning Hub
Replace all prompt file references with skills guidance throughout the Learning Hub. Skills are the preferred customization primitive because they support agent discovery via extended frontmatter, can bundle reference files and scripts, and are portable across coding agent systems via the Agent Skills specification. - Create what-are-agents-skills-instructions.md (replaces prompts article) - Create creating-effective-skills.md (replaces prompts tutorial) - Delete what-are-agents-prompts-instructions.md and creating-effective-prompts.md - Update copilot-configuration-basics.md directory structure and examples - Update defining-custom-instructions.md comparisons and cross-references - Update glossary: deprecate Prompt entry, add Skill definition - Update understanding-copilot-context.md and before-after examples - Update learning-hub index.astro slugs Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Aaron Powell
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: 'Before/After Customization Examples'
|
||||
description: 'See real-world transformations showing how custom agents, prompts, and instructions dramatically improve GitHub Copilot effectiveness.'
|
||||
description: 'See real-world transformations showing how custom agents, skills, and instructions dramatically improve GitHub Copilot effectiveness.'
|
||||
authors:
|
||||
- GitHub Copilot Learning Hub Team
|
||||
lastUpdated: '2025-12-12'
|
||||
@@ -11,14 +11,14 @@ tags:
|
||||
- fundamentals
|
||||
- best-practices
|
||||
relatedArticles:
|
||||
- ./what-are-agents-prompts-instructions.md
|
||||
- ./creating-effective-prompts.md
|
||||
- ./what-are-agents-skills-instructions.md
|
||||
- ./creating-effective-skills.md
|
||||
- ./defining-custom-instructions.md
|
||||
---
|
||||
|
||||
# Before/After Customization Examples
|
||||
|
||||
The power of GitHub Copilot customization becomes clear when you see concrete examples of how agents, prompts, and instructions transform everyday development workflows. This article presents real-world scenarios showing the dramatic difference between default Copilot behavior and customized experiences that align with your team's standards, tools, and practices.
|
||||
The power of GitHub Copilot customization becomes clear when you see concrete examples of how agents, skills, and instructions transform everyday development workflows. This article presents real-world scenarios showing the dramatic difference between default Copilot behavior and customized experiences that align with your team's standards, tools, and practices.
|
||||
|
||||
> Note: The following examples illustrate typical before-and-after scenarios. The actual before and after code may vary depending on the model used and any other context present at generation time.
|
||||
|
||||
@@ -142,18 +142,18 @@ describe('UserService', () => {
|
||||
- No mocking strategy
|
||||
- Incomplete assertions
|
||||
|
||||
### After: With Custom Testing Prompt
|
||||
### After: With Custom Testing Skill
|
||||
|
||||
Create `.github/prompts/generate-test.prompt.md`:
|
||||
Create a skill folder `.github/skills/generate-tests/` with a `SKILL.md`:
|
||||
|
||||
````markdown
|
||||
---
|
||||
agent: 'agent'
|
||||
description: 'Generate comprehensive test suites using our testing patterns'
|
||||
tools: ['changes', 'codebase', 'edit/editFiles', 'execute/runTests']
|
||||
model: 'gpt-4o'
|
||||
name: generate-tests
|
||||
description: 'Generate comprehensive test suites using our testing patterns, including fixtures, setup/teardown, and thorough assertions'
|
||||
---
|
||||
|
||||
# generate-tests
|
||||
|
||||
Generate a comprehensive test suite for the selected code following these patterns:
|
||||
|
||||
**Setup Requirements**:
|
||||
@@ -173,6 +173,8 @@ Generate a comprehensive test suite for the selected code following these patter
|
||||
- Check error messages and types for failure cases
|
||||
- Assert side effects (database changes, API calls, events)
|
||||
|
||||
See [references/test-patterns.md](references/test-patterns.md) for standard patterns and [templates/test-template.ts](templates/test-template.ts) for a starter structure.
|
||||
|
||||
**Example Pattern**:
|
||||
```typescript
|
||||
import { setupTestDb, cleanupTestDb } from '@/test/setup';
|
||||
@@ -215,7 +217,7 @@ describe('UserService', () => {
|
||||
Generate tests following this pattern for the selected code.
|
||||
````
|
||||
|
||||
Now when you select code and use `/generate-test`, Copilot produces comprehensive test suites:
|
||||
Now when you select code and use `/generate-tests`, or when an agent detects a testing need, Copilot produces comprehensive test suites:
|
||||
|
||||
```typescript
|
||||
// user-service.test.ts
|
||||
@@ -436,18 +438,18 @@ Developers manually review pull requests and write comments, which can be time-c
|
||||
|
||||
Time investment: 20-30 minutes per PR
|
||||
|
||||
### After: With Code Review Prompt
|
||||
### After: With Code Review Skill
|
||||
|
||||
Create `prompts/review-pr.prompt.md`:
|
||||
Create a skill folder `skills/review-pr/` with a `SKILL.md`:
|
||||
|
||||
````markdown
|
||||
---
|
||||
agent: 'plan'
|
||||
description: 'Generate comprehensive code review with actionable feedback'
|
||||
tools: ['search/changes', 'search/codebase', 'edit/*']
|
||||
model: 'gpt-4o'
|
||||
name: review-pr
|
||||
description: 'Generate comprehensive code review with actionable feedback, covering correctness, security, performance, and maintainability'
|
||||
---
|
||||
|
||||
# review-pr
|
||||
|
||||
Analyze the current git diff and provide a structured code review with:
|
||||
|
||||
**Structure**:
|
||||
@@ -478,6 +480,8 @@ Use markdown with code blocks for suggestions. For each issue, provide:
|
||||
- Why it matters
|
||||
- Suggested fix with code example
|
||||
|
||||
See [references/review-checklist.md](references/review-checklist.md) for the standard review checklist.
|
||||
|
||||
Example format:
|
||||
## 🔴 Critical Issues
|
||||
|
||||
@@ -495,7 +499,7 @@ function processUser(user: User) {
|
||||
```
|
||||
````
|
||||
|
||||
Using this prompt on a PR generates structured, actionable feedback:
|
||||
Using this skill on a PR (via `/review-pr` or agent invocation) generates structured, actionable feedback:
|
||||
|
||||
````markdown
|
||||
## Summary
|
||||
@@ -579,7 +583,7 @@ app.post('/login', loginLimiter, authController.login);
|
||||
These examples demonstrate how customization transforms GitHub Copilot from a general-purpose assistant into a team-specific expert:
|
||||
|
||||
1. **Instructions** embed your team's patterns into every suggestion automatically
|
||||
2. **Prompts** standardize workflows and ensure consistent quality
|
||||
2. **Skills** standardize workflows with bundled resources and enable agent discovery
|
||||
3. **Agents** bring specialized expertise for complex domains
|
||||
4. **Combination** of all three creates a comprehensive development assistant
|
||||
|
||||
|
||||
@@ -10,7 +10,7 @@ tags:
|
||||
- setup
|
||||
- fundamentals
|
||||
relatedArticles:
|
||||
- ./what-are-agents-prompts-instructions.md
|
||||
- ./what-are-agents-skills-instructions.md
|
||||
- ./understanding-copilot-context.md
|
||||
prerequisites:
|
||||
- Basic familiarity with GitHub Copilot
|
||||
@@ -39,7 +39,7 @@ Repository settings live in your codebase (typically in `.github/` although some
|
||||
|
||||
**Common repository-level customizations**:
|
||||
- Custom instructions for coding conventions
|
||||
- Reusable prompts for common tasks
|
||||
- Reusable skills for common tasks
|
||||
- Specialized agents for project workflows
|
||||
- Custom agents for domain expertise
|
||||
|
||||
@@ -160,9 +160,11 @@ A well-organized Copilot configuration directory looks like this:
|
||||
├── agents/
|
||||
│ ├── terraform-expert.agent.md
|
||||
│ └── api-reviewer.agent.md
|
||||
├── prompts/
|
||||
│ ├── generate-test.prompt.md
|
||||
│ └── refactor-component.prompt.md
|
||||
├── skills/
|
||||
│ ├── generate-tests/
|
||||
│ │ └── SKILL.md
|
||||
│ └── refactor-component/
|
||||
│ └── SKILL.md
|
||||
└── instructions/
|
||||
├── typescript-conventions.instructions.md
|
||||
└── api-design.instructions.md
|
||||
@@ -186,23 +188,29 @@ Guide users through creating, reviewing, and deploying infrastructure code.
|
||||
|
||||
**When to use**: Create agents for domain-specific tasks like infrastructure management, API design, or security reviews.
|
||||
|
||||
### Reusable Prompts
|
||||
### Reusable Skills
|
||||
|
||||
Prompts are reusable templates for common tasks. Store them in `.github/prompts/`.
|
||||
Skills are self-contained folders that package reusable capabilities. Store them in `.github/skills/`.
|
||||
|
||||
**Example prompt** (`generate-test.prompt.md`):
|
||||
**Example skill** (`generate-tests/SKILL.md`):
|
||||
```markdown
|
||||
---
|
||||
mode: 'agent'
|
||||
description: 'Generate comprehensive unit tests for a component'
|
||||
name: generate-tests
|
||||
description: 'Generate comprehensive unit tests for a component, covering happy path, edge cases, and error conditions'
|
||||
---
|
||||
|
||||
# generate-tests
|
||||
|
||||
Generate unit tests for the selected code that:
|
||||
- Cover all public methods and edge cases
|
||||
- Use our testing conventions from @testing-utils.ts
|
||||
- Include descriptive test names
|
||||
|
||||
See [references/test-patterns.md](references/test-patterns.md) for standard patterns.
|
||||
```
|
||||
|
||||
Skills can also bundle reference files, templates, and scripts in their folder, giving the AI richer context than a single file can provide. Unlike the older prompt format, skills can be discovered and invoked by agents automatically.
|
||||
|
||||
**When to use**: For repetitive tasks your team performs regularly, like generating tests, creating documentation, or refactoring patterns.
|
||||
|
||||
### Instructions Files
|
||||
@@ -234,7 +242,7 @@ Follow these steps to establish effective team-wide Copilot configuration:
|
||||
Start by creating the `.github/` directory in your repository root:
|
||||
|
||||
```bash
|
||||
mkdir -p .github/{agents,prompts,instructions}
|
||||
mkdir -p .github/{agents,skills,instructions}
|
||||
```
|
||||
|
||||
### 2. Document Your Conventions
|
||||
@@ -255,17 +263,19 @@ Our team follows these practices:
|
||||
- Keep functions small and focused
|
||||
```
|
||||
|
||||
### 3. Build Reusable Prompts
|
||||
### 3. Build Reusable Skills
|
||||
|
||||
Identify repetitive tasks and create prompts for them:
|
||||
Identify repetitive tasks and create skills for them:
|
||||
|
||||
```markdown
|
||||
<!-- .github/prompts/add-error-handling.prompt.md -->
|
||||
<!-- .github/skills/add-error-handling/SKILL.md -->
|
||||
---
|
||||
mode: 'agent'
|
||||
description: 'Add comprehensive error handling to existing code'
|
||||
name: add-error-handling
|
||||
description: 'Add comprehensive error handling to existing code following team patterns'
|
||||
---
|
||||
|
||||
# add-error-handling
|
||||
|
||||
Add error handling to the selected code:
|
||||
- Catch and handle potential errors
|
||||
- Log errors with context
|
||||
@@ -285,7 +295,7 @@ Add error handling to the selected code:
|
||||
Make Copilot configuration part of your onboarding process:
|
||||
|
||||
1. Point new members to your `.github/` directory
|
||||
2. Explain which agents and prompts exist and when to use them
|
||||
2. Explain which agents and skills exist and when to use them
|
||||
3. Encourage exploration and contributions
|
||||
4. Include example usage in your project README
|
||||
|
||||
@@ -368,8 +378,8 @@ A: Use user-level settings in your IDE for personal preferences that should appl
|
||||
|
||||
Now that you understand Copilot configuration, explore how to create powerful customizations:
|
||||
|
||||
- **[What are Agents, Prompts, and Instructions](../learning-hub/what-are-agents-prompts-instructions/)** - Understand the customization types you can configure
|
||||
- **[What are Agents, Skills, and Instructions](../learning-hub/what-are-agents-skills-instructions/)** - Understand the customization types you can configure
|
||||
- **[Understanding Copilot Context](../learning-hub/understanding-copilot-context/)** - Learn how configuration affects context usage
|
||||
- **[Defining Custom Instructions](../learning-hub/defining-custom-instructions/)** - Create persistent context for your projects
|
||||
- **[Creating Effective Prompts](../learning-hub/creating-effective-prompts/)** - Build reusable task templates
|
||||
- **[Creating Effective Skills](../learning-hub/creating-effective-skills/)** - Build reusable task folders with bundled assets
|
||||
- **Building Custom Agents** _(coming soon)_ - Develop specialized assistants
|
||||
|
||||
@@ -1,425 +0,0 @@
|
||||
---
|
||||
title: 'Creating Effective Prompts'
|
||||
description: 'Master the art of writing reusable, shareable prompt templates that deliver consistent results across your team.'
|
||||
authors:
|
||||
- GitHub Copilot Learning Hub Team
|
||||
lastUpdated: '2025-12-02'
|
||||
estimatedReadingTime: '9 minutes'
|
||||
tags:
|
||||
- prompts
|
||||
- customization
|
||||
- fundamentals
|
||||
relatedArticles:
|
||||
- ./what-are-agents-prompts-instructions.md
|
||||
- ./defining-custom-instructions.md
|
||||
- ./building-custom-agents.md
|
||||
prerequisites:
|
||||
- Basic understanding of GitHub Copilot chat
|
||||
---
|
||||
|
||||
Prompts are reusable templates that package specific tasks into shareable chat commands. They enable teams to standardize common workflows tasks 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 prompts that solve real development challenges.
|
||||
|
||||
## What Are Prompts?
|
||||
|
||||
Prompts (`*.prompt.md`) are markdown files that define:
|
||||
|
||||
- **Command name**: How users invoke the prompt (e.g., `/code-review`)
|
||||
- **Task description**: What the prompt accomplishes
|
||||
- **Execution mode**: Whether it acts as an agent or simple ask
|
||||
- **Tool requirements**: Which Copilot capabilities it needs (codebase search, terminal, etc.)
|
||||
- **Message template**: The actual instructions Copilot executes
|
||||
|
||||
**Key Points**:
|
||||
- Prompts require explicit invocation (unlike instructions which apply automatically)
|
||||
- They capture proven workflows as reusable templates
|
||||
- They can accept user input variables for customization
|
||||
- They work across different codebases without modification
|
||||
|
||||
### How Prompts Differ from Other Customizations
|
||||
|
||||
**Prompts vs Instructions**:
|
||||
- Prompts are invoked explicitly; instructions apply automatically
|
||||
- Prompts drive specific tasks; instructions provide ongoing context
|
||||
- Use prompts for workflows you trigger on demand; use instructions for standards that always apply
|
||||
|
||||
**Prompts vs Agents**:
|
||||
- Prompts are task-focused templates; agents are specialized personas
|
||||
- Prompts work with standard Copilot tools; agents may require MCP servers or custom integrations
|
||||
- Use prompts for repeatable tasks; use agents for complex multi-step workflows
|
||||
|
||||
## Anatomy of a Prompt
|
||||
|
||||
Every effective prompt has three parts: frontmatter configuration, task description, and execution instructions.
|
||||
|
||||
**Example - Simple Prompt**:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: 'Generate unit tests for the selected code'
|
||||
tools: ['codebase']
|
||||
---
|
||||
|
||||
Generate comprehensive unit tests for the selected 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 description tells users what the prompt does
|
||||
- `tools` array specifies codebase access is needed
|
||||
- Requirements provide specific, actionable guidance
|
||||
- Template is generic enough to work across different projects
|
||||
|
||||
## Frontmatter Configuration
|
||||
|
||||
The YAML frontmatter controls how Copilot executes your prompt.
|
||||
|
||||
### Essential Fields
|
||||
|
||||
**agent**: Execution mode for the prompt
|
||||
```yaml
|
||||
agent: 'agent' # Full agent capabilities with tools
|
||||
# OR
|
||||
agent: 'ask' # Simple question/answer without tool execution
|
||||
# OR
|
||||
agent: 'My Custom Agent' # Use a specific custom agent
|
||||
```
|
||||
|
||||
**description**: Brief summary of what the prompt does
|
||||
```yaml
|
||||
description: 'Generate conventional commit messages from staged changes'
|
||||
```
|
||||
|
||||
**tools**: Array of capabilities the prompt needs
|
||||
```yaml
|
||||
tools: ['codebase', 'runCommands', 'edit']
|
||||
```
|
||||
|
||||
**model**: Preferred AI model (optional but recommended)
|
||||
```yaml
|
||||
model: Claude Sonnet 4
|
||||
```
|
||||
|
||||
### Common Tool Combinations
|
||||
|
||||
**Code Generation**:
|
||||
```yaml
|
||||
tools: ['codebase', 'edit', 'search']
|
||||
```
|
||||
|
||||
**Testing**:
|
||||
```yaml
|
||||
tools: ['codebase', 'runCommands', 'testFailure']
|
||||
```
|
||||
|
||||
**Git Operations**:
|
||||
```yaml
|
||||
tools: ['runCommands/runInTerminal', 'changes']
|
||||
```
|
||||
|
||||
**Documentation**:
|
||||
```yaml
|
||||
tools: ['codebase', 'search', 'edit', 'fetch']
|
||||
```
|
||||
|
||||
**Code Review**:
|
||||
```yaml
|
||||
tools: ['changes', 'codebase', 'problems', 'search']
|
||||
```
|
||||
|
||||
## Real Examples from the Repository
|
||||
|
||||
The awesome-copilot-hub repository includes over 110 prompt files demonstrating production patterns.
|
||||
|
||||
### Conventional Commits
|
||||
|
||||
See [conventional-commit.prompt.md](https://github.com/github/awesome-copilot/blob/main/prompts/conventional-commit.prompt.md) for automating commit messages:
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: 'Generate conventional commit messages from staged changes'
|
||||
tools: ['runCommands/runInTerminal', 'runCommands/getTerminalOutput']
|
||||
---
|
||||
|
||||
### 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 prompt automates a repetitive task (writing commit messages) with a proven template.
|
||||
|
||||
### Specification Creation
|
||||
|
||||
See [create-specification.prompt.md](https://github.com/github/awesome-copilot/blob/main/prompts/create-specification.prompt.md) for structured documentation:
|
||||
|
||||
```markdown
|
||||
---
|
||||
mode: 'agent'
|
||||
description: 'Create a new specification file optimized for AI consumption'
|
||||
tools: ['codebase', 'search', 'edit', 'fetch']
|
||||
---
|
||||
|
||||
Your goal is to create a specification file for ${input:SpecPurpose}.
|
||||
|
||||
The specification must:
|
||||
- Use precise, unambiguous language
|
||||
- Follow structured formatting for easy parsing
|
||||
- Define all acronyms and domain terms
|
||||
- Include examples and edge cases
|
||||
- Be self-contained without external dependencies
|
||||
|
||||
Save in /spec/ directory as: spec-[purpose].md
|
||||
```
|
||||
|
||||
This prompt uses a variable (`${input:SpecPurpose}`) to customize each invocation.
|
||||
|
||||
### Code Review Automation
|
||||
|
||||
See [review-and-refactor.prompt.md](https://github.com/github/awesome-copilot/blob/main/prompts/review-and-refactor.prompt.md) for systematic code analysis:
|
||||
|
||||
```markdown
|
||||
---
|
||||
mode: 'agent'
|
||||
description: 'Comprehensive code review and refactoring suggestions'
|
||||
tools: ['changes', 'codebase', 'problems', 'search']
|
||||
model: Claude Sonnet 4
|
||||
---
|
||||
|
||||
Review the current changes or selected code for:
|
||||
|
||||
1. **Code Quality**: Readability, maintainability, complexity
|
||||
2. **Best Practices**: Language idioms, framework patterns
|
||||
3. **Performance**: Algorithm efficiency, resource usage
|
||||
4. **Security**: Input validation, authentication, sensitive data
|
||||
5. **Testing**: Test coverage, edge cases, error handling
|
||||
|
||||
Provide specific refactoring suggestions with code examples.
|
||||
```
|
||||
|
||||
This prompt combines multiple analysis dimensions into a single repeatable workflow.
|
||||
|
||||
## Writing Effective Prompt Templates
|
||||
|
||||
### Structure Your Prompts
|
||||
|
||||
**1. Start with clear objectives**:
|
||||
```markdown
|
||||
Your goal is to [specific task] for [specific target].
|
||||
```
|
||||
|
||||
**2. Define requirements explicitly**:
|
||||
```markdown
|
||||
Requirements:
|
||||
- Must follow [standard/pattern]
|
||||
- Should include [specific element]
|
||||
- Avoid [anti-pattern]
|
||||
```
|
||||
|
||||
**3. Provide examples**:
|
||||
```markdown
|
||||
### Good Example
|
||||
[Show desired output]
|
||||
|
||||
### What to Avoid
|
||||
[Show problematic patterns]
|
||||
```
|
||||
|
||||
**4. Specify output format**:
|
||||
```markdown
|
||||
Output format:
|
||||
- File location: [path pattern]
|
||||
- Naming convention: [format]
|
||||
- Structure: [expected sections]
|
||||
```
|
||||
|
||||
### Use Variables for Customization
|
||||
|
||||
Prompts can accept user input through variables:
|
||||
|
||||
**Simple variable**:
|
||||
```markdown
|
||||
Generate a ${input:ComponentType} component named ${input:ComponentName}.
|
||||
```
|
||||
|
||||
**Variable with context**:
|
||||
```markdown
|
||||
Create tests for ${selection} using the ${input:TestFramework} framework.
|
||||
```
|
||||
|
||||
**Referencing files**:
|
||||
```markdown
|
||||
Update the documentation in ${file:README.md} based on changes in ${selection}.
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **One purpose per prompt**: Focus on a single task or workflow
|
||||
- **Make it generic**: Write prompts that work across different projects
|
||||
- **Be explicit**: Avoid ambiguous language; specify exact requirements
|
||||
- **Include context**: Reference patterns, standards, or examples from the codebase
|
||||
- **Name descriptively**: Use clear, action-oriented names: `generate-tests.prompt.md`, not `helper.prompt.md`
|
||||
- **Test thoroughly**: Verify prompts work with different inputs and codebases
|
||||
- **Document tools needed**: Specify all required Copilot capabilities
|
||||
- **Version your prompts**: Update lastUpdated when making changes
|
||||
|
||||
### 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 prompts**:
|
||||
```markdown
|
||||
## Step 1: Analysis
|
||||
[Analyze requirements]
|
||||
|
||||
## Step 2: Generation
|
||||
[Generate code]
|
||||
|
||||
## Step 3: Validation
|
||||
[Check output]
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Agent Mode with Multi-Step Workflow
|
||||
|
||||
```markdown
|
||||
---
|
||||
mode: 'agent'
|
||||
description: 'Scaffold new feature with tests and documentation'
|
||||
tools: ['codebase', 'edit', 'search']
|
||||
---
|
||||
|
||||
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
|
||||
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.
|
||||
```
|
||||
|
||||
### Ask Mode for Quick Questions
|
||||
|
||||
```markdown
|
||||
---
|
||||
mode: 'ask'
|
||||
description: 'Explain code architecture and design patterns'
|
||||
---
|
||||
|
||||
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.
|
||||
```
|
||||
|
||||
### Terminal Automation
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: 'Run test suite and report failures'
|
||||
tools: ['runCommands/runInTerminal', 'testFailure']
|
||||
---
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
## Common Questions
|
||||
|
||||
**Q: How do I invoke a prompt?**
|
||||
|
||||
A: In VS Code, open Copilot Chat and type the filename without extension. For example, `/code-review` invokes `code-review.prompt.md`. Alternatively, use the Copilot prompt picker UI.
|
||||
|
||||
**Q: Can prompts modify multiple files?**
|
||||
|
||||
A: Yes, if the prompt uses `agent: 'agent'` and includes the `edit` tool. The prompt can analyze, generate, and apply changes across multiple files.
|
||||
|
||||
**Q: How do I share prompts with my team?**
|
||||
|
||||
A: Store prompts in your repository's `.github/prompts/` directory. They're automatically available to all team members with Copilot access when working in that repository.
|
||||
|
||||
**Q: Can I chain multiple prompts together?**
|
||||
|
||||
A: Not directly, but you can create a comprehensive prompt that incorporates multiple steps. For complex workflows spanning many operations, consider creating a custom agent instead.
|
||||
|
||||
**Q: Should prompts include code examples?**
|
||||
|
||||
A: Yes, for clarity. Show examples of desired output format, patterns to follow, or anti-patterns to avoid. Keep examples focused and relevant.
|
||||
|
||||
## Common Pitfalls to Avoid
|
||||
|
||||
- ❌ **Too generic**: "Review this code" doesn't provide enough guidance
|
||||
✅ **Instead**: Specify what to review: quality, security, performance, style
|
||||
|
||||
- ❌ **Too specific**: Hardcoding file paths, names, or project-specific details
|
||||
✅ **Instead**: Use variables and pattern matching: `${input:FileName}`, `${selection}`
|
||||
|
||||
- ❌ **Missing tools**: Prompt needs codebase access but doesn't declare it
|
||||
✅ **Instead**: Explicitly list all required tools in frontmatter
|
||||
|
||||
- ❌ **Ambiguous language**: "Fix issues if you find any"
|
||||
✅ **Instead**: "Identify code smells and suggest specific refactorings with examples"
|
||||
|
||||
- ❌ **No examples**: Abstract requirements without concrete guidance
|
||||
✅ **Instead**: Include "Good Example" and "What to Avoid" sections
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that you understand effective prompts, you can:
|
||||
|
||||
- **Explore Repository Examples**: Browse [Prompts Directory](../prompts/) - Over 110 production prompts for diverse workflows
|
||||
- **Learn About Agents**: Building Custom Agents _(coming soon)_ - When to upgrade from prompts to full agents
|
||||
- **Understand Instructions**: [Defining Custom Instructions](../learning-hub/defining-custom-instructions/) - Complement prompts with automatic context
|
||||
- **Decision Framework**: Choosing the Right Customization _(coming soon)_ - When to use prompts vs other types
|
||||
|
||||
**Suggested Reading Order**:
|
||||
1. This article (creating effective prompts)
|
||||
2. Building Custom Agents _(coming soon)_ - More sophisticated workflows
|
||||
3. Choosing the Right Customization _(coming soon)_ - Decision guidance
|
||||
|
||||
---
|
||||
403
website/src/content/learning-hub/creating-effective-skills.md
Normal file
403
website/src/content/learning-hub/creating-effective-skills.md
Normal file
@@ -0,0 +1,403 @@
|
||||
---
|
||||
title: 'Creating Effective Skills'
|
||||
description: 'Master the art of writing reusable, shareable skill folders that deliver consistent results across your team.'
|
||||
authors:
|
||||
- GitHub Copilot Learning Hub Team
|
||||
lastUpdated: '2026-02-26'
|
||||
estimatedReadingTime: '9 minutes'
|
||||
tags:
|
||||
- skills
|
||||
- customization
|
||||
- fundamentals
|
||||
relatedArticles:
|
||||
- ./what-are-agents-skills-instructions.md
|
||||
- ./defining-custom-instructions.md
|
||||
prerequisites:
|
||||
- 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](https://agentskills.io/home)
|
||||
- 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`):
|
||||
|
||||
```markdown
|
||||
---
|
||||
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:
|
||||
|
||||
```markdown
|
||||
## 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
|
||||
```yaml
|
||||
name: generate-tests
|
||||
```
|
||||
|
||||
**description**: Brief summary of what the skill does and when to use it (10–1024 characters, wrapped in single quotes)
|
||||
```yaml
|
||||
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.
|
||||
|
||||
## Real Examples from the Repository
|
||||
|
||||
The awesome-copilot repository includes skill folders demonstrating production patterns.
|
||||
|
||||
### Conventional Commits
|
||||
|
||||
See [`skills/conventional-commit/SKILL.md`](https://github.com/github/awesome-copilot/tree/main/skills/conventional-commit) for automating commit messages:
|
||||
|
||||
```markdown
|
||||
---
|
||||
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/`](https://github.com/github/awesome-copilot/tree/main/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**:
|
||||
```markdown
|
||||
# skill-name
|
||||
|
||||
Your goal is to [specific task] for [specific target].
|
||||
```
|
||||
|
||||
**2. Add "When to Use" guidance** (helps agent discovery):
|
||||
```markdown
|
||||
## 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**:
|
||||
```markdown
|
||||
## Requirements
|
||||
|
||||
- Must follow [standard/pattern]
|
||||
- Should include [specific element]
|
||||
- Avoid [anti-pattern]
|
||||
```
|
||||
|
||||
**4. Reference bundled assets**:
|
||||
```markdown
|
||||
## References
|
||||
|
||||
- Follow patterns in [references/patterns.md](references/patterns.md)
|
||||
- Use template from [templates/starter.json](templates/starter.json)
|
||||
```
|
||||
|
||||
**5. Provide examples**:
|
||||
```markdown
|
||||
### 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**:
|
||||
```markdown
|
||||
## Step 1: Analysis
|
||||
[Analyze requirements]
|
||||
|
||||
## Step 2: Generation
|
||||
[Generate code]
|
||||
|
||||
## Step 3: Validation
|
||||
[Check output]
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Multi-Step Workflow with References
|
||||
|
||||
```markdown
|
||||
---
|
||||
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
|
||||
|
||||
```markdown
|
||||
---
|
||||
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
|
||||
|
||||
```markdown
|
||||
---
|
||||
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 two ways. Users can type the skill name as a `/command` in VS Code Chat (e.g., `/generate-tests`). Agents can also discover and invoke skills automatically based on the skill's description and the user's intent.
|
||||
|
||||
**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 agents chain multiple skills?**
|
||||
|
||||
A: Agents can discover and invoke 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.
|
||||
|
||||
## 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](../skills/) for production skills covering diverse workflows
|
||||
- **Learn About Agents**: Building Custom Agents _(coming soon)_ — When to upgrade from skills to full agents
|
||||
- **Understand Instructions**: [Defining Custom Instructions](../learning-hub/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 _(coming soon)_ — More sophisticated workflows
|
||||
3. Choosing the Right Customization _(coming soon)_ — Decision guidance
|
||||
|
||||
---
|
||||
@@ -10,14 +10,14 @@ tags:
|
||||
- customization
|
||||
- fundamentals
|
||||
relatedArticles:
|
||||
- ./what-are-agents-prompts-instructions.md
|
||||
- ./creating-effective-prompts.md
|
||||
- ./what-are-agents-skills-instructions.md
|
||||
- ./creating-effective-skills.md
|
||||
- ./copilot-configuration-basics.md
|
||||
prerequisites:
|
||||
- Basic understanding of GitHub Copilot features
|
||||
---
|
||||
|
||||
Custom instructions are persistent configuration files that automatically guide GitHub Copilot's behavior when working with specific files or directories in your codebase. Unlike prompts that require explicit invocation, instructions work silently in the background, ensuring Copilot consistently follows your team's standards, conventions, and architectural decisions.
|
||||
Custom instructions are persistent configuration files that automatically guide GitHub Copilot's behavior when working with specific files or directories in your codebase. Unlike skills that require explicit invocation (by a user or an agent), instructions work silently in the background, ensuring Copilot consistently follows your team's standards, conventions, and architectural decisions.
|
||||
|
||||
This article explains how to create effective custom instructions, when to use them, and how they integrate with your development workflow.
|
||||
|
||||
@@ -38,10 +38,10 @@ Custom instructions are markdown files (`.instructions.md`) that contain:
|
||||
|
||||
### How Instructions Differ from Other Customizations
|
||||
|
||||
**Instructions vs Prompts**:
|
||||
- Instructions are always active for matching files; prompts require explicit invocation
|
||||
- Instructions provide passive context; prompts drive specific tasks
|
||||
- Use instructions for standards that apply repeatedly; use prompts for one-time operations
|
||||
**Instructions vs Skills**:
|
||||
- Instructions are always active for matching files; skills require explicit invocation (by users or agents)
|
||||
- Instructions provide passive context; skills drive specific tasks with bundled resources
|
||||
- Use instructions for standards that apply repeatedly; use skills for on-demand operations
|
||||
|
||||
**Instructions vs Agents**:
|
||||
- Instructions are lightweight context; agents are specialized personas with tool access
|
||||
@@ -307,11 +307,11 @@ A: No. Instructions are for persistent standards that apply repeatedly. Document
|
||||
Now that you understand custom instructions, you can:
|
||||
|
||||
- **Explore Repository Examples**: Browse [Instructions Directory](../instructions/) - Over 120 real-world examples covering frameworks, languages, and domains
|
||||
- **Learn About Prompts**: [Creating Effective Prompts](../learning-hub/creating-effective-prompts/) - Discover when to use prompts instead of instructions
|
||||
- **Learn About Skills**: [Creating Effective Skills](../learning-hub/creating-effective-skills/) - Discover when to use skills instead of instructions
|
||||
- **Understand Agents**: Building Custom Agents _(coming soon)_ - See how agents complement instructions for complex workflows
|
||||
- **Configuration Basics**: [Copilot Configuration Basics](../learning-hub/copilot-configuration-basics/) - Learn how to organize and manage your customizations
|
||||
|
||||
**Suggested Reading Order**:
|
||||
1. This article (defining custom instructions)
|
||||
2. [Creating Effective Prompts](../learning-hub/creating-effective-prompts/) - Learn complementary customization type
|
||||
2. [Creating Effective Skills](../learning-hub/creating-effective-skills/) - Learn complementary customization type
|
||||
3. Choosing the Right Customization _(coming soon)_ - Decision framework for when to use each type
|
||||
|
||||
@@ -10,13 +10,13 @@ tags:
|
||||
- terminology
|
||||
- reference
|
||||
relatedArticles:
|
||||
- ./what-are-agents-prompts-instructions.md
|
||||
- ./what-are-agents-skills-instructions.md
|
||||
- ./copilot-configuration-basics.md
|
||||
---
|
||||
|
||||
# GitHub Copilot Terminology Glossary
|
||||
|
||||
New to GitHub Copilot customization? This glossary defines common terms you'll encounter while exploring agents, prompts, instructions, and related concepts in the Awesome GitHub Copilot ecosystem.
|
||||
New to GitHub Copilot customization? This glossary defines common terms you'll encounter while exploring agents, skills, instructions, and related concepts in the Awesome GitHub Copilot ecosystem.
|
||||
|
||||
Use this page as a quick reference when reading articles in the Learning Hub or browsing the repository.
|
||||
|
||||
@@ -30,7 +30,7 @@ A specialized configuration file (`*.agent.md`) that defines a GitHub Copilot pe
|
||||
|
||||
**When to use**: For recurring workflows that benefit from deep tooling integrations and persistent conversational context.
|
||||
|
||||
**Learn more**: [What are Agents, Prompts, and Instructions](/learning-hub/what-are-agents-prompts-instructions/)
|
||||
**Learn more**: [What are Agents, Skills, and Instructions](/learning-hub/what-are-agents-skills-instructions/)
|
||||
|
||||
---
|
||||
|
||||
@@ -56,9 +56,9 @@ Previously, "chat mode" was an alternative term for [Agent](#agent) that describ
|
||||
|
||||
**Note**: Collections are a concept specific to the Awesome GitHub Copilot repository and are not part of standard GitHub Copilot terminology.
|
||||
|
||||
A curated grouping of related prompts, instructions, and agents organized around a specific theme or workflow. Collections are defined in YAML files (`*.collection.yml`) in the `collections/` directory and help users discover related customizations together.
|
||||
A curated grouping of related skills, instructions, and agents organized around a specific theme or workflow. Collections are defined in YAML files (`*.collection.yml`) in the `collections/` directory and help users discover related customizations together.
|
||||
|
||||
**Example**: The "Awesome Copilot" collection bundles meta-prompts for discovering and generating GitHub Copilot customizations.
|
||||
**Example**: The "Awesome Copilot" collection bundles meta-skills for discovering and generating GitHub Copilot customizations.
|
||||
|
||||
**Learn more**: [Collections README](../../docs/README.collections.md)
|
||||
|
||||
@@ -87,7 +87,7 @@ The front matter is what controls:
|
||||
- **Model selection**: Which AI model powers the customization
|
||||
- **Scope**: Where the customization applies (e.g., `applyTo` patterns for instructions)
|
||||
|
||||
**Note**: Not all fields are common across all customization types. Refer to the specific documentation for agents, prompts, or instructions to see which fields apply to each type.
|
||||
**Note**: Not all fields are common across all customization types. Refer to the specific documentation for agents, skills, or instructions to see which fields apply to each type.
|
||||
|
||||
**Example**:
|
||||
```yaml
|
||||
@@ -99,7 +99,7 @@ tools: ['codebase']
|
||||
---
|
||||
```
|
||||
|
||||
**Used in**: Prompts, agents, instructions, and Learning Hub articles.
|
||||
**Used in**: Skills, agents, instructions, and Learning Hub articles.
|
||||
|
||||
---
|
||||
|
||||
@@ -126,11 +126,11 @@ A configuration file (`*.instructions.md`) that provides persistent background c
|
||||
|
||||
**When to use**: For long-lived guidance that applies across many sessions, like coding standards or compliance requirements.
|
||||
|
||||
**Learn more**: [What are Agents, Prompts, and Instructions](/learning-hub/what-are-agents-prompts-instructions/), [Defining Custom Instructions](/learning-hub/defining-custom-instructions/)
|
||||
**Learn more**: [What are Agents, Skills, and Instructions](/learning-hub/what-are-agents-skills-instructions/), [Defining Custom Instructions](/learning-hub/defining-custom-instructions/)
|
||||
|
||||
---
|
||||
|
||||
## Prompts & Interactions
|
||||
## Skills & Interactions
|
||||
|
||||
### Persona
|
||||
|
||||
@@ -144,13 +144,28 @@ The identity, tone, and behavioral characteristics defined for an [Agent](#agent
|
||||
|
||||
### Prompt
|
||||
|
||||
A reusable chat template (`*.prompt.md`) that captures a specific task or workflow. Prompts define the message content Copilot should execute and can include mode hints, model preferences, and tool recommendations. They're invoked using the `/` command in GitHub Copilot Chat.
|
||||
**Deprecated** — Prompts (`*.prompt.md`) were reusable chat templates that captured specific tasks or workflows, invoked using the `/` command in GitHub Copilot Chat. Prompts have been superseded by [Skills](#skill), which offer the same slash-command invocation plus agent discovery, bundled assets, and cross-platform portability.
|
||||
|
||||
**Example**: `/create-readme` might execute a prompt that generates comprehensive README documentation.
|
||||
If you have existing prompts, consider migrating them to skills. See [Creating Effective Skills](/learning-hub/creating-effective-skills/) for guidance.
|
||||
|
||||
**When to use**: For standardizing how Copilot responds to recurring tasks without needing long-lived conversational state.
|
||||
**See**: [Skill](#skill)
|
||||
|
||||
**Learn more**: [What are Agents, Prompts, and Instructions](/learning-hub/what-are-agents-prompts-instructions/), [Creating Effective Prompts](/learning-hub/creating-effective-prompts/)
|
||||
---
|
||||
|
||||
### Skill
|
||||
|
||||
A self-contained folder containing a `SKILL.md` file and optional bundled assets (reference documents, templates, scripts) that packages a reusable capability for GitHub Copilot. Skills follow the open [Agent Skills specification](https://agentskills.io/home) and can be invoked by users via `/command` or discovered and invoked by agents automatically.
|
||||
|
||||
**Key advantages**:
|
||||
- **Agent discovery**: Extended frontmatter lets agents find and invoke skills automatically
|
||||
- **Bundled assets**: Reference files, templates, and scripts provide richer context
|
||||
- **Cross-platform**: Portable across coding agent systems via the Agent Skills specification
|
||||
|
||||
**Example**: A `/generate-tests` skill might include a `SKILL.md` with testing instructions, a `references/test-patterns.md` with common patterns, and a `templates/test-template.ts` starter file.
|
||||
|
||||
**When to use**: For standardizing how Copilot responds to recurring tasks, especially when bundled resources improve quality.
|
||||
|
||||
**Learn more**: [What are Agents, Skills, and Instructions](/learning-hub/what-are-agents-skills-instructions/), [Creating Effective Skills](/learning-hub/creating-effective-skills/)
|
||||
|
||||
---
|
||||
|
||||
@@ -175,7 +190,7 @@ Capabilities that GitHub Copilot can invoke to perform actions or retrieve infor
|
||||
1. **Built-in tools**: Native capabilities like `codebase` (code search), `terminalCommand` (running commands), and `web` (web search)
|
||||
2. **MCP tools**: External integrations provided by MCP servers (e.g., database queries, cloud resource management, or API calls)
|
||||
|
||||
Agents and prompts can specify which tools they require or recommend in their front matter.
|
||||
Agents and skills can specify which tools they require or recommend in their front matter.
|
||||
|
||||
**Example front matter**:
|
||||
```yaml
|
||||
|
||||
@@ -10,7 +10,7 @@ tags:
|
||||
- fundamentals
|
||||
- how-it-works
|
||||
relatedArticles:
|
||||
- ./what-are-agents-prompts-instructions.md
|
||||
- ./what-are-agents-skills-instructions.md
|
||||
---
|
||||
|
||||
Context is the foundation of how GitHub Copilot generates relevant, accurate suggestions. Understanding what Copilot "sees" and how it uses that information helps you write better prompts, get higher-quality completions, and work more effectively with AI assistance. This article explains the types of context Copilot uses and how to optimize your development environment for better results.
|
||||
@@ -156,7 +156,7 @@ A: Yes, you have several ways to control context:
|
||||
- Open/close files to change what's available to Copilot
|
||||
- Use `#` mentions to explicitly reference specific files, symbols or functions
|
||||
- Configure `.gitignore` to exclude files from workspace context
|
||||
- Use instructions and prompts to provide persistent context for specific scenarios
|
||||
- Use instructions and skills to provide persistent context for specific scenarios
|
||||
|
||||
**Q: Does closing a file remove it from context?**
|
||||
|
||||
@@ -166,7 +166,7 @@ A: Yes, closing a file can remove it from Copilot's active context. However, fil
|
||||
|
||||
Now that you understand how context works in GitHub Copilot, explore these related topics:
|
||||
|
||||
- **[What are Agents, Prompts, and Instructions](../learning-hub/what-are-agents-prompts-instructions/)** - Learn about customization types that provide persistent context
|
||||
- **[What are Agents, Skills, and Instructions](../learning-hub/what-are-agents-skills-instructions/)** - Learn about customization types that provide persistent context
|
||||
- **[Copilot Configuration Basics](../learning-hub/copilot-configuration-basics/)** - Configure settings to optimize context usage
|
||||
- **[Creating Effective Prompts](../learning-hub/creating-effective-prompts/)** - Use context effectively in your prompts
|
||||
- **[Creating Effective Skills](../learning-hub/creating-effective-skills/)** - Use context effectively in your skills
|
||||
- **Common Pitfalls and Solutions** _(coming soon)_ - Avoid context-related mistakes
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
title: 'What are Agents, Prompts, and Instructions'
|
||||
title: 'What are Agents, Skills, and Instructions'
|
||||
description: 'Understand the primary customization primitives that extend GitHub Copilot for specific workflows.'
|
||||
authors:
|
||||
- GitHub Copilot Learning Hub Team
|
||||
lastUpdated: '2025-11-25'
|
||||
lastUpdated: '2026-02-26'
|
||||
estimatedReadingTime: '7 minutes'
|
||||
---
|
||||
|
||||
@@ -25,22 +25,34 @@ When you assign an issue to Copilot or open the **Agents** panel in VS Code, the
|
||||
- You want Copilot to proactively execute commands or fetch context via MCP.
|
||||
- You need persona-level guardrails that persist throughout a coding session.
|
||||
|
||||
## Prompts
|
||||
## Skills
|
||||
|
||||
Prompts (`*.prompt.md`) capture reusable chat macros. They define:
|
||||
Skills are self-contained folders that package reusable capabilities for GitHub Copilot. Each skill lives in its own directory and contains a `SKILL.md` file along with optional bundled assets such as reference documents, templates, and scripts.
|
||||
|
||||
- A short name (used as `/command` in VS Code Chat).
|
||||
- Optional mode and model hints (for example, `plan` vs `code` or `gpt-4.1-mini`).
|
||||
- Recommended tools to enable before running the prompt.
|
||||
- The actual message template Copilot should execute.
|
||||
A `SKILL.md` defines:
|
||||
|
||||
Prompts shine when you want consistency across teammates—think "Create release notes" or "Audit accessibility". Store them in `prompts/` and trigger them directly from VS Code.
|
||||
- A **name** (used as a `/command` in VS Code Chat and for agent discovery).
|
||||
- A **description** that tells agents and users when the skill is relevant.
|
||||
- Detailed instructions for how the skill should be executed.
|
||||
- References to any bundled assets the skill needs.
|
||||
|
||||
### When to reach for a prompt
|
||||
Skills follow the open [Agent Skills specification](https://agentskills.io/home), making them portable across coding agent systems beyond GitHub Copilot.
|
||||
|
||||
- You want to standardize how Copilot responds to a task.
|
||||
- You prefer to drive the conversation, but with guardrails.
|
||||
- You do not need Copilot to maintain long-lived state beyond a single invocation.
|
||||
### Why skills over prompts
|
||||
|
||||
Skills replace the earlier prompt file (`*.prompt.md`) pattern and offer several advantages:
|
||||
|
||||
- **Agent discovery**: Skills include extended frontmatter that lets agents find and invoke them automatically—prompts could only be triggered manually via a slash command.
|
||||
- **Richer context**: Skills can bundle reference files, scripts, templates, and other assets alongside their instructions, giving the AI much more to work with.
|
||||
- **Cross-platform portability**: The Agent Skills specification is supported across multiple coding agent systems, so your investment travels with you.
|
||||
- **Slash command support**: Like prompts, skills can still be invoked via `/command` in VS Code Chat.
|
||||
|
||||
### When to reach for a skill
|
||||
|
||||
- You want to standardize how Copilot responds to a recurring task.
|
||||
- You need bundled resources (templates, schemas, scripts) to complete the task.
|
||||
- You want agents to discover and invoke the capability automatically.
|
||||
- You prefer to drive the conversation, but with guardrails and rich context.
|
||||
|
||||
## Instructions
|
||||
|
||||
@@ -63,7 +75,7 @@ Instructions sit under `instructions/` and can be scoped globally, per language,
|
||||
Think of these artifacts as complementary layers:
|
||||
|
||||
1. **Instructions** lay the groundwork with long-lived guardrails.
|
||||
2. **Prompts** let you trigger quick workflows or templates on demand.
|
||||
2. **Skills** let you trigger rich, reusable workflows on demand—and let agents discover those workflows automatically.
|
||||
3. **Agents** bring the most opinionated behavior, bundling tools and instructions into a single persona.
|
||||
|
||||
By combining all three, teams can achieve:
|
||||
@@ -75,7 +87,7 @@ By combining all three, teams can achieve:
|
||||
## Next steps
|
||||
|
||||
- Explore the rest of the **Fundamentals** track for deeper dives on chat modes, collections, and MCP servers.
|
||||
- Browse the [Awesome Agents](../agents/), [Prompts](../prompts/), and [Instructions](../instructions/) directories for inspiration.
|
||||
- Browse the [Awesome Agents](../agents/), [Skills](../skills/), and [Instructions](../instructions/) directories for inspiration.
|
||||
- Try generating your own artifacts, then add them to the repo to keep the Learning Hub evolving.
|
||||
|
||||
---
|
||||
@@ -6,11 +6,11 @@ const base = import.meta.env.BASE_URL;
|
||||
const articles = await getCollection('learning-hub');
|
||||
|
||||
const fundamentalsOrder = [
|
||||
'what-are-agents-prompts-instructions',
|
||||
'what-are-agents-skills-instructions',
|
||||
'understanding-copilot-context',
|
||||
'copilot-configuration-basics',
|
||||
'defining-custom-instructions',
|
||||
'creating-effective-prompts',
|
||||
'creating-effective-skills',
|
||||
'before-after-customization-examples',
|
||||
];
|
||||
|
||||
|
||||
Reference in New Issue
Block a user