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: "**"
---

undefined

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

undefined

/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"]
---

undefined

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

undefined

---
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)"
---

undefined

---
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
---

undefined

/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
---

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

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

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

undefined

"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"