Add agent-customization skill with primitives documentation (#3196)

* Add agent-customization skill with primitives documentation

* Update assets/prompts/skills/agent-customization/primitives/workspace-instructions.md

Co-authored-by: Copilot <[email protected]>

* fix: rename agentCustomizationSkill setting to follow Advanced naming convention

* Updated skills.md based on spec

---------

Co-authored-by: Copilot <[email protected]>

Author: digitarald

assets/prompts/skills/agent-customization/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: agent-customization
+description: 'Work with VS Code agent customization files (.instructions.md, .prompt.md, .agent.md, SKILL.md, copilot-instructions.md, AGENTS.md). Use when asked to: create, update, review, fix, or debug instructions/prompts/agents/skills; save coding preferences or conventions; understand how customization files work; troubleshoot why instructions/skills are not applying or being ignored; compare customization approaches; migrate or refactor existing customizations; set up project guidelines; configure applyTo patterns; define tool restrictions; create reusable workflows; build custom agent modes or personas; package domain knowledge; add frontmatter; fix YAML syntax; or share team standards.'
+---
+
+# Agent Customization
+
+## Decision Flow
+
+| Primitive | When to Use |
+|-----------|-------------|
+| Workspace Instructions | Always-on, applies everywhere in the project |
+| File Instructions | Explicit via `applyTo` patterns, or on-demand via `description` |
+| MCP | Integrates external systems, APIs, or data |
+| Custom Agents | Subagents for context isolation, or multi-stage workflows with tool restrictions |
+| Prompts | Single focused task with parameterized inputs |
+| Skills | On-demand workflow with bundled assets (scripts/templates) |
+
+## Quick Reference
+
+Consult the reference docs for templates, domain examples, advanced frontmatter options, asset organization, anti-patterns, and creation checklists.
+
+| Type | File | Location | Key Field | Reference |
+|------|------|----------|-----------|---------|
+| Workspace Instructions | `copilot-instructions.md`, `AGENTS.md` | `.github/` or root | N/A (always applies) | [Link](./primitives/workspace-instructions.md) |
+| File Instructions | `*.instructions.md` | `.github/instructions/` | `applyTo` (explicit), `description` (on-demand) | [Link](./primitives/instructions.md) |
+| Prompts | `*.prompt.md` | `.github/prompts/` | `description` (required) | [Link](./primitives/prompts.md) |
+| Custom Agents | `*.agent.md` | `.github/agents/` | `description` (on-demand), `infer` (subagent) | [Link](./primitives/agents.md) |
+| Skills | `SKILL.md` | `.github/skills/<name>/` | `description` (on-demand) | [Link](./primitives/skills.md) |
+
+**User-level**: `{{USER_PROMPTS_FOLDER}}/` (*.prompt.md, *.instructions.md, *.agent.md; not skills)
+Customizations roam with user's settings sync
+
+## Creation Process
+
+If you need to explore or validate patterns in the codebase, use a read-only subagent. If the ask-questions tool is available, use it to interview the user and clarify requirements.
+
+Follow these steps when creating any customization file.
+
+### 1. Determine Scope
+
+Ask the user where they want the customization:
+- **Workspace**: For project-specific, team-shared customizations → `.github/` folder
+- **User profile**: For personal, cross-workspace customizations → `{{USER_PROMPTS_FOLDER}}/`
+
+### 2. Choose the Right Primitive
+
+Use the Decision Flow above to select the appropriate file type based on the user's need.
+
+### 3. Create the File
+
+Create the file directly at the appropriate path:
+- Use the location tables in each reference file
+- Include required frontmatter as needed
+- Add the body content following the templates
+
+### 4. Validate
+
+After creating:
+- Confirm the file is in the correct location
+- Verify frontmatter syntax (YAML between `---` markers)
+- Check that `description` is present and meaningful
+
+## Edge Cases
+
+**Instructions vs Skill?** Does this apply to *most* work, or *specific* tasks? Most → Instructions. Specific → Skill.
+
+**Skill vs Prompt?** Multi-step workflow with bundled assets → Skill. Single focused task with inputs → Prompt.
+
+**Skill vs Custom Agent?** Same capabilities for all steps → Skill. Need context isolation (subagent returns single output) or different tool restrictions per stage → Custom Agent.

assets/prompts/skills/agent-customization/primitives/agents.md

@@ -0,0 +1,150 @@
+# [Custom Agents (.agent.md)](https://code.visualstudio.com/docs/copilot/customization/custom-agents)
+
+Custom personas with specific tools, instructions, and behaviors.
+
+## Locations
+
+| Path | Scope |
+|------|-------|
+| `.github/agents/*.agent.md` | Workspace |
+| `<profile>/agents/*.agent.md` | User profile |
+
+## Frontmatter
+
+```yaml
+---
+description: "<required>"    # For agent picker and subagent discovery
+name: "Agent Name"           # Optional, defaults to filename
+tools: ["search", "fetch"]   # Optional: built-in, MCP (<server>/*), extension
+model: "Claude Sonnet 4"     # Optional, uses picker default
+argument-hint: "Task..."     # Optional, input guidance
+infer: true                  # Optional, enable on-demand subagent discovery (default: true)
+handoffs: [...]              # Optional, transitions to other agents
+---
+```
+
+## Tools
+
+Specify tool names in the `tools` array. Sources: built-in tools, tool sets, MCP servers (`<server>/*`), or extension-contributed tools.
+
+To discover available tools, search your current tool list or use the tool search capability.
+
+**Special**: `[]` = no tools, omit = defaults. Body reference: `#tool:<name>`
+
+### Tool Aliases
+
+Common aliases for restricting agent capabilities:
+
+| Alias | Purpose |
+|-------|---------|
+| `shell` | Execute shell commands |
+| `read` | Read file contents |
+| `edit` | Edit files (exact tools vary) |
+| `search` | Search files or text |
+| `custom-agent` | Invoke other custom agents as subagents |
+| `web` | Fetch URLs and web search |
+| `todo` | Create and manage task lists |
+
+### Common Restriction Patterns
+
+```yaml
+# Read-only agent (no editing, no execution)
+tools: ["read", "search"]
+
+# MCP-only agent
+tools: ["myserver/*"]
+
+# No terminal access
+tools: ["read", "edit", "search"]
+
+# Planning agent (research only)
+tools: ["search", "web", "read"]
+```
+
+For the full list of available tools, see the [VS Code documentation](https://code.visualstudio.com/docs/copilot/customization/custom-agents).
+
+## Template
+
+```markdown
+---
+description: "Generate implementation plans"
+tools: ["search", "fetch", "githubRepo", "usages"]
+---
+You are in planning mode. Generate plans, don't edit code. Include: Overview, Requirements, Steps, Testing.
+```
+
+## Invocation
+
+- **Manual**: Agents dropdown or `Chat: Switch Agent...` command
+- **On-demand (subagent)**: When `infer: true`, parent agent can delegate based on `description` match—like skills and instructions
+
+## When to Use
+
+**Key Signal**: Orchestrated multi-stage processes with role-based tool restrictions. Different stages need different capabilities or strict handoffs.
+
+## Domain Examples
+
+| Domain | Example Workflow |
+|--------|------------------|
+| Engineering | planner → implementer → reviewer → deployer |
+| Product | research → strategy → execution → measurement |
+| Analytics | scope → build → analyze → report |
+| Support | triage → troubleshoot → escalate → close |
+| Content | research → write → edit → publish |
+
+## Creation Process
+
+### 1. Gather Requirements
+
+- What role or persona should this agent embody?
+- What specific tools does this role need (and which should it NOT have)?
+- Should this be workspace-specific or personal (user profile)?
+- Will this agent hand off to other agents?
+
+### 2. Determine Location
+
+| Scope | Path |
+|-------|------|
+| Workspace | `.github/agents/<name>.agent.md` |
+| User profile | `<profile>/agents/<name>.agent.md` |
+
+### 3. Create the File
+
+```markdown
+---
+description: "<role description for agent picker>"
+tools: ["<minimal tool set>"]
+---
+You are a <role>. Your responsibilities:
+- <primary responsibility>
+- <constraints on behavior>
+
+<Specific instructions for this role>
+```
+
+### 4. Configure Handoffs (optional)
+
+If this agent is part of a workflow:
+```yaml
+handoffs:
+  - agent: "next-stage-agent"
+    condition: "When <trigger condition>"
+```
+
+## Core Principles
+
+1. **Single role per agent**: Each agent embodies one persona with focused responsibilities
+2. **Minimal tool set**: Only include tools required for the role—excess tools dilute focus and increase risk
+3. **Clear boundaries**: Define what the agent should NOT do as clearly as what it should do
+4. **Explicit handoffs**: When workflows span agents, define clear transition triggers
+5. **Discoverable via description**: The `description` field drives agent picker display—make it actionable
+6. **Keyword-rich for subagent discovery**: When `infer: true`, the `description` determines automatic delegation—include trigger words and use cases so the parent agent knows when to invoke this subagent
+
+## Anti-patterns
+
+- **Swiss-army agents**: Agents with many tools that try to do everything
+- **Missing constraints**: Agents without clear boundaries on what they shouldn't attempt
+- **Role confusion**: Description doesn't match the persona defined in the body
+- **Circular handoffs**: Agent A hands to B which hands back to A without progress criteria
+- **Tool sprawl**: Using `tools: []` to disable all tools when specific restrictions would suffice
+- **Vague subagent descriptions**: Generic descriptions like "A helpful agent" that don't help the parent decide when to delegate—use phrases like "use proactively after code changes" for clear triggers