doc_version: "2025-03 (VS Code 1.102+)"
source_urls:
  - https://code.visualstudio.com/docs/copilot/customization/overview
  - https://code.visualstudio.com/docs/copilot/customization/custom-instructions
  - https://code.visualstudio.com/docs/copilot/customization/prompt-files
  - https://code.visualstudio.com/docs/copilot/customization/custom-agents
  - https://code.visualstudio.com/docs/copilot/customization/agent-skills
  - https://code.visualstudio.com/docs/copilot/customization/hooks
  - https://code.visualstudio.com/docs/copilot/customization/agent-plugins

Do you want it ON automatically for every request?
├─ YES → Instructions (.instructions.md / copilot-instructions.md / AGENTS.md)
└─ NO, I invoke it manually →
       Does it need persistent persona, tool restrictions, or model choice?
       ├─ YES → Custom Agent (.agent.md)
       └─ NO →
              Is it a reusable multi-agent portable capability?
              ├─ YES → Agent Skill (SKILL.md)
              └─ NO → Prompt File (.prompt.md)

Do you want to run shell commands around agent actions?
└─ YES → Hook (hooks/*.json)

Do you want to bundle everything for distribution?
└─ YES → Agent Plugin (plugin.json)

---
name: "React Standards"          # Optional – shown in UI
description: "React/TSX rules"   # Optional – describes scope
applyTo: "**/*.tsx"              # Glob – omit or use "**" for all files
---

---
applyTo: "**"
---
# Project Coding Standards

## General
- Use TypeScript for all new code; strict mode enabled.
- Prefer functional patterns; avoid classes unless needed.
- Max line length: 100 chars. 2-space indentation.

## Naming
- PascalCase: components, interfaces, types, enums.
- camelCase: variables, functions, hooks.
- ALL_CAPS: constants.

## Error handling
- Use try/catch for all async operations.
- Always log errors with context (module + function name).

## Testing
- Jest + React Testing Library.
- One test file per module, co-located (`*.test.ts`).

---
name: "TypeScript Standards"
applyTo: "**/*.ts,**/*.tsx"
---
# TypeScript Rules

- Enable `strictNullChecks` and `noImplicitAny`.
- Prefer `interface` over `type` for object shapes.
- Use `unknown` instead of `any` for external data.
- Always type function return values explicitly.

/init                         → generate workspace-wide copilot-instructions.md
/create-instruction           → generate a targeted .instructions.md file

"github.copilot.chat.codeGeneration.useInstructionFiles": true,
"chat.instructionsFilesLocations": {
  ".github/instructions": true
},
"chat.useAgentsMdFile": true

---
name: "generate-component"      # Used as /generate-component slash command
description: "Scaffold a new React component with tests"
agent: "agent"                  # ask | agent | plan | <custom-agent-name>
model: "claude-sonnet-4-5"      # Optional – overrides model picker
tools:                          # Available tools for this prompt
  - "search/codebase"
  - "vscode/askQuestions"
  - "githubRepo"
mode: "agent"                   # Optional – ask | agent | plan
---

---
name: "new-component"
description: "Scaffold a React component with TypeScript, Tailwind, and tests"
agent: "agent"
tools: ["search/codebase", "vscode/askQuestions", "edit"]
---
# Generate React Component

Use #tool:vscode/askQuestions to ask for:
1. Component name (PascalCase)
2. Props interface (list prop names and types)
3. Should it be a Server Component? (yes/no)

Then generate:
- `src/components/<Name>/<Name>.tsx` – main component
- `src/components/<Name>/<Name>.test.tsx` – unit tests
- `src/components/<Name>/index.ts` – barrel export

Follow the coding standards in [copilot-instructions.md](../../.github/copilot-instructions.md).

---
name: "pr-description"
description: "Generate a structured pull request description from staged changes"
agent: "ask"
tools: ["search/codebase"]
---
# Pull Request Description

Analyze the changes in the current branch and generate a PR description with these sections:

## Summary
Brief one-sentence description of what this PR does.

## Changes
- List each meaningful change as a bullet point.

## Testing
- How was this tested?
- Any edge cases covered?

## Screenshots
(if UI changes – note: add manually)

---
name: "api-endpoint"
description: "Generate a REST API endpoint"
---
Create a ${input:httpMethod:GET|POST|PUT|DELETE} endpoint at `${input:path:/api/resource}`.

Use Zod for input validation. Follow the patterns in [api-standards.md](../docs/api-standards.md).

/create-prompt    → AI guides you through creating a prompt file

---
name: "Planner"                  # Agent name shown in dropdown
description: "Generates implementation plans without writing code"
tools:                           # Whitelist of allowed tools
  - "search"
  - "fetch"
  - "githubRepo"
  - "usages"
model:                           # Tried in order (fallback chain)
  - "claude-opus-4-5 (copilot)"
  - "GPT-4o (copilot)"
target: "vscode"                 # vscode | github-copilot | omit for both
handoffs:                        # Suggested next-step buttons
  - label: "Start Implementation"
    agent: "agent"               # Built-in agent or custom agent name
    prompt: "Implement the plan above."
    send: false                  # true = auto-submit
hooks:                           # Agent-scoped hooks (runs only when this agent is active)
  PostToolUse:
    - type: "command"
      command: "echo 'Tool used'"
---

---
name: "Reviewer"
description: "Reviews code for quality, security, and best practices. Does NOT modify files."
tools:
  - "read"
  - "search"
  - "vscode/askQuestions"
  - "fetch"
model: "claude-opus-4-5 (copilot)"
---
# Code Reviewer

You are a senior engineer conducting a thorough code review. Your role is to **analyze only** – never make direct code changes.

## Review Checklist
- [ ] Code quality and readability
- [ ] Potential bugs or logic errors
- [ ] Security vulnerabilities (XSS, injection, auth issues)
- [ ] Performance considerations
- [ ] Test coverage gaps
- [ ] Adherence to [project standards](./../copilot-instructions.md)

## Output Format
Structure feedback with clear headings, code references (file + line number), and severity:
- 🔴 **Critical** – must fix before merge
- 🟡 **Warning** – should fix
- 🟢 **Suggestion** – optional improvement

---
name: "Planner"
description: "Creates detailed implementation plans. Switches to implementation when ready."
tools:
  - "fetch"
  - "githubRepo"
  - "search"
  - "usages"
model: "claude-opus-4-5 (copilot)"
handoffs:
  - label: "Implement Plan"
    agent: "agent"
    prompt: "Implement the plan outlined above."
    send: false
---
# Planning Mode

You are in **planning mode**. Generate an implementation plan. Do **not** write or edit any code.

## Plan Structure

### Overview
Brief description of the feature or change.

### Files to create / modify
List each file with the reason.

### Implementation steps
Numbered steps in order. Include dependencies.

### Risks & open questions
Things to clarify before implementing.

### Estimated complexity
S / M / L / XL with reasoning.

/create-agent     → AI generates a .agent.md file
/agents           → Open Configure Custom Agents menu

.github/skills/
└── skill-name/
    ├── SKILL.md          ← Required. Metadata + instructions.
    ├── scripts/          ← Executable scripts referenced from SKILL.md
    ├── references/       ← Docs, examples, large reference files
    └── assets/           ← Templates, fixtures

---
name: "skill-name"               # Used as /skill-name slash command
description: >                   # CRITICAL: be specific about WHEN to use.
  Max 1024 chars. Include both what it does AND trigger contexts.
hint: "[file-path] [options]"    # Hint shown in chat input on invocation
showInSlashMenu: true            # false to hide from / menu (still auto-loads)
manualOnly: false                # true = only invocable via /skill-name
---

---
name: "test-writer"
description: >
  Guide for writing unit and integration tests with Jest and React Testing Library.
  Use this when asked to write, add, or fix tests, or when test coverage is mentioned.
hint: "[file to test] [test type: unit|integration]"
showInSlashMenu: true
manualOnly: false
---
# Test Writer

## When to use this skill
- Writing new unit tests for components or utilities
- Writing integration tests for API endpoints
- Fixing failing tests
- Improving test coverage

## Test setup
- Framework: Jest + React Testing Library
- Test files: co-located as `*.test.ts` or `*.test.tsx`
- Coverage threshold: 80% per module

## Writing unit tests

Follow the Arrange-Act-Assert pattern:

```typescript
describe('ComponentName', () => {
  it('should render correctly', () => {
    // Arrange
    const props = { ... };

    // Act
    render(<Component {...props} />);

    // Assert
    expect(screen.getByRole('button')).toBeInTheDocument();
  });
});

### Key settings

```json
"chat.agentSkillsLocations": [".github/skills"]

/create-skill     → AI generates a skill directory with SKILL.md
/skills           → Open Configure Skills menu

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "npx prettier --write \"$TOOL_INPUT_FILE_PATH\"",
        "windows": "npx prettier --write \"%TOOL_INPUT_FILE_PATH%\"",
        "timeout": 30
      }
    ],
    "PreToolUse": [
      {
        "type": "command",
        "command": "./scripts/validate-tool.sh",
        "timeout": 15
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "type": "command",
        "command": "npx prettier --write \"$TOOL_INPUT_FILE_PATH\" 2>/dev/null || true",
        "windows": "npx prettier --write \"%TOOL_INPUT_FILE_PATH%\" 2>nul",
        "timeout": 30
      }
    ]
  }
}

{
  "hooks": {
    "Stop": [
      {
        "type": "command",
        "command": "npm run lint && npm run typecheck",
        "windows": "npm run lint && npm run typecheck",
        "timeout": 60
      }
    ]
  }
}

/create-hook     → AI generates a hook JSON file

"chat.hookFilesLocations": {
  ".github/hooks": true
}

my-plugin/
├── plugin.json              ← Required metadata
├── skills/
│   └── my-skill/
│       └── SKILL.md
├── agents/
│   └── my-agent.agent.md
├── hooks/
│   └── post-edit.json
└── mcp/
    └── server-config.json

{
  "name": "my-plugin",
  "displayName": "My Plugin",
  "version": "1.0.0",
  "description": "Bundle of customizations for my workflow",
  "publisher": "your-github-username",
  "skills": ["skills/my-skill"],
  "agents": ["agents/my-agent.agent.md"],
  "hooks": ["hooks/post-edit.json"],
  "mcpServers": []
}

// settings.json – add custom marketplace
"chat.plugins.marketplaces": ["owner/repo"],

// Or register a local plugin path
"chat.plugins.paths": ["/path/to/my-plugin"]

"chat.plugins.enabled": true

/init                  → workspace-wide copilot-instructions.md
/create-instruction    → targeted .instructions.md
/create-prompt         → .prompt.md file
/create-agent          → .agent.md file
/create-skill          → agent skill directory
/create-hook           → hook JSON file

Command Palette → "Chat: Open Chat Customizations"