Why this catalog exists Link to heading

The customization library includes 19 examples, but teams often need help turning them into day-to-day workflows.

This catalog focuses on three things for each example:

What problem it solves
What design pattern it demonstrates
How to adapt it without overfitting

Use cases Link to heading

Developers who want one reference for the full customization library
Team leads deciding where to start in production repositories
Engineers who need examples they can run immediately

Coverage map Link to heading

The 19 examples are split into three groups:

9 custom instruction examples
6 prompt file examples
4 custom agent examples

Diagram: Library coverage Link to heading

Part A: Custom instructions (9) Link to heading

1) Your first custom instructions Link to heading

What it teaches:

Start with simple, always-on coding preferences
Compare behavior before and after adding instructions

Pattern:

Broad standards in one baseline file

Adaptation tip:

Keep this file concise and move niche rules to path-specific instruction files.

Minimal working file — .github/copilot-instructions.md:

# Coding defaults

- Use TypeScript for new source files.
- Prefer early returns over nested conditionals.
- Validate external inputs before processing.
- Add tests for new behavior and bug fixes.
- Run lint and tests before finalizing changes.

Ask Copilot to add a new API endpoint and compare the response with and without this file in place. The second response should include input validation and a test suggestion.

2) Concept explainer Link to heading

What it teaches:

Teaching-oriented explanation style
Progressive complexity and practical examples

Pattern:

Instruction-guided pedagogy for onboarding and docs

Adaptation tip:

Add your team glossary and common misconceptions to reduce repeated clarification cycles.

3) Debugging tutor Link to heading

What it teaches:

Structured debugging process instead of guesswork
Question-led diagnosis and reproducibility discipline

Pattern:

Root-cause-first troubleshooting guidance

Adaptation tip:

Add your stack-specific observability tools and log locations.

4) Code reviewer Link to heading

What it teaches:

Review lens across security, performance, and code quality
Constructive and actionable feedback style

Pattern:

Risk-prioritized review rubric

Adaptation tip:

Encode your merge-blocking criteria and severity conventions.

Minimal working file — .github/copilot-instructions.md extension or a dedicated instruction:

# Code review lens

When reviewing code:
- Flag security issues first: unvalidated input, hardcoded secrets, unsafe deserialization.
- Then flag performance: N+1 queries, unbounded loops, unnecessary allocations.
- Then flag maintainability: names that obscure intent, duplication, missing error handling.
- For each finding, state: location, severity (Critical / Major / Minor), and one concrete fix.
- End with up to three positive observations.

Pair this with the review-code prompt file (example 14) for an on-demand slash command.

5) GitHub Actions helper Link to heading

What it teaches:

Path-scoped instructions for workflow files
Security-first CI guidance

Pattern:

File-targeted standards using applyTo

Adaptation tip:

Add your organization-approved actions list and permission defaults.

6) Pull request assistant Link to heading

What it teaches:

Structured PR descriptions and review focus areas
Review communication consistency

Pattern:

Standardized PR narrative template

Adaptation tip:

Add deployment checklist items specific to your environment.

7) Issue manager Link to heading

What it teaches:

Better bug and feature issue structure
Actionable issue hygiene and triage signals

Pattern:

Template-driven issue quality framework

Adaptation tip:

Add required metadata fields for your backlog process.

8) Accessibility auditor Link to heading

What it teaches:

Accessibility-first generation and review criteria
Practical checks for semantic structure and assistive tech support

Pattern:

Path-specific domain constraints with testable rules

Adaptation tip:

Add your required audit tooling in CI and manual QA checklists.

9) Testing automation Link to heading

What it teaches:

Test authoring discipline with framework-specific guidance
Edge-case and dependency-mocking patterns

Pattern:

Tests-only path-specific instruction profile

Adaptation tip:

Align examples to your existing test directory and naming conventions.

Part B: Prompt files (6) Link to heading

10) Your first prompt file Link to heading

What it teaches:

Prompt file anatomy with frontmatter and inputs
Running a reusable slash command

Pattern:

Interactive explanation workflow with user variables

Adaptation tip:

Add output structure sections so explanations are easier to compare and review.

Minimal working file — .github/prompts/explain-code.prompt.md:

---
name: explain-code
description: Explain selected code with clear language and a usage example
argument-hint: detail=high|medium|low
agent: agent
---

Explain the selected code with ${input:detail:medium} level of detail.

Code:
${selection}

Return exactly three sections:
1. What it does (one paragraph)
2. Step-by-step flow
3. One realistic usage example with inputs and expected output

In VS Code, select a function in the editor, open Copilot Chat, run /explain-code detail=high, and press Enter. Because the prompt enforces structure, each response includes the same three sections and is easy to compare across files.

11) Create README Link to heading

What it teaches:

Repository-wide documentation synthesis workflow
Scannable output structure and practical constraints

Pattern:

Project analysis to targeted docs output

Adaptation tip:

Add your required policy sections, such as support matrix and release process.

12) Onboarding plan Link to heading

What it teaches:

Phased onboarding decomposition
Personalization using user inputs

Pattern:

Multi-phase planning template

Adaptation tip:

Add links to internal onboarding docs and starter issues.

13) Document API Link to heading

What it teaches:

OpenAPI-oriented documentation generation
Structured schema and response coverage requirements

Pattern:

Output-constrained machine-readable documentation generation

Adaptation tip:

Add API versioning and auth scheme rules used by your platform.

14) Review code Link to heading

What it teaches:

Structured review report output format
Explicit issue classification

Pattern:

Human-readable review report with severity buckets

Adaptation tip:

Add acceptance thresholds for PR approval recommendations.

15) Generate unit tests Link to heading

What it teaches:

Behavioral test generation strategy
Input, error, and side-effect coverage guidance

Pattern:

Parameterized test generation task with framework selection

Adaptation tip:

Bind it to your project framework defaults to reduce setup friction.

Part C: Custom agents (4) Link to heading

16) Your first custom agent Link to heading

What it teaches:

Agent profile fundamentals
Purpose-bound specialist behavior

Pattern:

Documentation specialist with scoped responsibility

Adaptation tip:

Keep explicit non-goals in the prompt body to prevent scope drift.

Minimal working file — .github/agents/readme-specialist.agent.md:

---
name: readme-specialist
description: Reviews and improves README files for clarity and completeness
tools: ["read", "search", "edit"]
user-invocable: true
disable-model-invocation: true
---

You are a documentation specialist focused on README quality.

Always:
- Assess the current README for missing sections (description, installation, usage, contributing, license).
- Suggest concrete additions or rewrites for unclear sections.
- Keep language direct and scannable.

Do not:
- Modify source code files.
- Suggest infrastructure or architecture changes.
- Generate content beyond the scope of the current repository.

Select this agent in the GitHub.com Agents panel or the VS Code agent picker, then ask: “Review the README and suggest improvements.” The disable-model-invocation: true field keeps invocation explicit, so the agent does not auto-activate from general conversation context.

17) Implementation planner Link to heading

What it teaches:

Structured implementation planning format
Phased decomposition with risks and constraints

Pattern:

Plan-first specialist for pre-implementation design

Adaptation tip:

Add your architecture decision template and acceptance criteria format.

18) Bug fix teammate Link to heading

What it teaches:

Root-cause bug resolution workflow
Tight scope and minimal-change fix strategy

Pattern:

Reliability specialist with implementation bias

Adaptation tip:

Add bug severity definitions and regression test expectations.

19) Cleanup specialist Link to heading

What it teaches:

Maintainability cleanup and deduplication
Scope-aware refactor hygiene

Pattern:

Safe simplification specialist

Adaptation tip:

Require before/after validation checks for any cleanup task.

Cross-example implementation strategy Link to heading

To operationalize all 19 examples safely:

Start from one example per category
Pilot in one repository
Measure quality and cycle time changes
Expand to adjacent workflows
Standardize naming conventions and ownership

Scenario selector Link to heading

Use this quick selector:

Need always-on behavior: choose custom instruction pattern
Need repeatable slash command: choose prompt file pattern
Need specialist autonomous workflow: choose custom agent pattern

Hands-on mini labs Link to heading

Run these three mini labs to convert the catalog into practical muscle memory.

Lab A: Custom instructions Link to heading

Create .github/copilot-instructions.md:

# Team defaults

- Prefer explicit error handling.
- Add tests for behavior changes.
- Reuse existing modules before adding new abstractions.

Ask Copilot: “Add a deleteUser endpoint.” Without the instruction file, the response is usually a bare skeleton. With it, expect explicit error handling, test guidance, and reuse of existing deletion logic.

What a good response looks like:

// Reuses existing db module pattern
app.delete('/users/:id', async (req, res) => {
  const { id } = req.params;
  try {
    const deleted = await db.deleteUser(id);
    if (!deleted) {
      return res.status(404).json({ error: 'User not found', code: 'NOT_FOUND' });
    }
    res.status(204).send();
  } catch (err) {
    res.status(500).json({ error: 'Delete failed', code: 'DB_ERROR' });
  }
});

// Suggested test:
// DELETE /users/:id with unknown id → 404 NOT_FOUND
// DELETE /users/:id with valid id  → 204 No Content

Compared to the uninstructed version, this output adds error handling, structured error codes, and a concrete test suggestion.

Lab B: Prompt file Link to heading

Create .github/prompts/create-pr-summary.prompt.md:

---
name: create-pr-summary
description: Generate a structured PR summary from selected changes
agent: agent
---

Create a PR summary for this diff:
${selection}

Return sections:
- What changed
- Why it changed
- Risks
- Validation steps

Select a git diff in the editor, open Copilot Chat, and run /create-pr-summary. Run it on two different diffs and compare structure. Consistent sections are the main advantage over free-text prompting.

Lab C: Custom agent Link to heading

Create .github/agents/bug-fix-teammate.agent.md:

---
name: bug-fix-teammate
description: Diagnoses root cause and proposes minimal fix
tools: ["read", "search", "edit"]
user-invocable: true
disable-model-invocation: true
---

You are a bug-fix specialist.
Always return:
- Root cause
- Minimal patch plan
- Regression tests

Do not rewrite unrelated code. Do not change behavior beyond the reported bug.

Select the agent and describe a bug: “The calculateDiscount function returns 0 for corporate tier even though it should return 15%.” A well-scoped agent should identify the missing branch, propose a minimal patch, and list a regression test without refactoring unrelated code.

When all three labs produce structured, scoped, and consistent outputs, you have a strong foundation for the remaining 16 patterns.

Key takeaways Link to heading

The 19 examples are pattern blueprints, not final production artifacts.
Customize each example around your repository standards, process, and risk model.
Keep global context small and move specificity into prompts and agents.
Validate each adaptation with real tasks and track measurable quality signals.
Roll out gradually: pilot, measure, expand.

References Link to heading