---
name: agent-customization
description: **WORKFLOW SKILL** — Create, update, review, fix, or debug VS Code agent customization files (.instructions.md, .prompt.md, .agent.md, SKILL.md,…
---

# agent-customization

**WORKFLOW SKILL** — Create, update, review, fix, or debug VS Code agent customization files (.instructions.md, .prompt.md, .agent.md, SKILL.md,…

# agent-customizationby microsoft
**WORKFLOW SKILL** — Create, update, review, fix, or debug VS Code agent customization files (.instructions.md, .prompt.md, .agent.md, SKILL.md,…

`npx skills add https://github.com/microsoft/vscode-copilot-chat --skill agent-customization`Download ZIPGitHub

## Agent Customization

## Decision Flow

PrimitiveWhen to UseWorkspace InstructionsAlways-on, applies everywhere in the projectFile InstructionsExplicit via `applyTo` patterns, or on-demand via `description`MCPIntegrates external systems, APIs, or dataHooksDeterministic shell commands at agent lifecycle points (block tools, auto-format, inject context)Custom AgentsSubagents for context isolation, or multi-stage workflows with tool restrictionsPromptsSingle focused task with parameterized inputsSkillsOn-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. If the references are not enough, load the official documentation links for each primitive.

TypeFileLocationReferenceWorkspace Instructions`copilot-instructions.md`, `AGENTS.md``.github/` or rootLinkFile Instructions`*.instructions.md``.github/instructions/`LinkPrompts`*.prompt.md``.github/prompts/`LinkHooks`*.json``.github/hooks/`LinkCustom Agents`*.agent.md``.github/agents/`LinkSkills`SKILL.md``.github/skills/<name>/`, `.agents/skills/<name>/`, `.claude/skills/<name>/`Link
User-level: `{{VSCODE_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 → `{{VSCODE_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? Both appear as slash commands in chat (type `/`). 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.

Hooks vs Instructions? Instructions guide agent behavior (non-deterministic). Hooks enforce behavior via shell commands at lifecycle events like `PreToolUse` or `PostToolUse` — they can block operations, require approval, or run formatters deterministically. See hooks reference.

## Common Pitfalls

Description is the discovery surface. The `description` field is how the agent decides whether to load a skill, instruction, or agent. If trigger phrases aren't IN the description, the agent won't find it. Use the "Use when..." pattern with specific keywords.

YAML frontmatter silent failures. Unescaped colons in values, tabs instead of spaces, `name` that doesn't match folder name — all cause silent failures with no error message. Always quote descriptions that contain colons: `description: "Use when: doing X"`.

`applyTo: "**"` burns context. This means "always included for every file request" — it loads the instruction into the context window on every interaction, even when irrelevant. Use specific globs (`**/*.py`, `src/api/**`) unless the instruction truly applies to all files.

## More skills from microsoft
oss-growthby microsoftOSS growth hacker personapr-description-skillby microsoftTrigger this skill on any of the following intents:python-architectureby microsoftPython architect personasupply-chain-securityby microsoftSupply chain security expert personaskill-nameby microsoftDescription of what the skill does and when to use itwork-iterationsby microsoftList, create, and assign iterations for Azure DevOps projects and teams.djangoby microsoftBest practices for Django web development including models, views, templates, and testing.flaskby microsoftBest practices for Flask web development including routing, blueprints, and testing.

---

**Source**: https://github.com/microsoft/vscode-copilot-chat/tree/HEAD/assets/prompts/skills/agent-customization
**Author**: microsoft
**Discovered via**: mcpservers.org