agent-customization
- Repo stars 185,273
- Author updated Live
- Author repo vscode
- Domain
- Documentation
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- Author / version / license
- @microsoft · no license declared
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No special requirements
- Permissions
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: agent-customization
description: **WORKFLOW SKILL** — Create, update, review, fix, or debug VS Code agent customization files (.i…
category: documentation
runtime: no special runtime
---
# agent-customization output preview
## PART A: Task fit
- Use case: **WORKFLOW SKILL** — Create, update, review, fix, or debug VS Code agent customization files (.instructions.md, .prompt.md, .agent.md, SKILL.md, copilot-instructions.md, AGENTS.md). USE FOR: saving coding preferences; troubleshooting why instructions/skills/agents are ignored or not invoked; configuring applyTo patterns; defining tool restrictions; creating custom agent modes or specialized workflows; packaging domain knowledge; fixing YAML frontmatter syntax. DO NOT USE FOR: general coding questions (use default agent); runtime debugging or error diagnosis; MCP server configuration (use MCP docs directly); VS Code extension development. INVOKES: file system tools (read/write customization files), ask-questions tool (interview user for requirements), subagents for codebase exploration. FOR SINGLE OPERATIONS: For quick YAML frontmatter fixes or creating a single file from a known pattern, edit the file directly — no skill needed..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “Decision Flow / Quick Reference / Creation Process” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “**WORKFLOW SKILL** — Create, update, review, fix, or debug VS Code agent customization files (.instructions.md, .prompt.md, .agent.md, SKILL.md, copilot-instructions.md, AGENTS.md). USE FOR: saving coding preferences; troubleshooting why instructions/skills/agents are ignored or not invoked; configuring applyTo patterns; defining tool restrictions; creating custom agent modes or specialized workflows; packaging domain knowledge; fixing YAML frontmatter syntax. DO NOT USE FOR: general coding questions (use default agent); runtime debugging or error diagnosis; MCP server configuration (use MCP docs directly); VS Code extension development. INVOKES: file system tools (read/write customization files), ask-questions tool (interview user for requirements), subagents for codebase exploration. FOR SINGLE OPERATIONS: For quick YAML frontmatter fixes or creating a single file from a known pattern, edit the file directly — no skill needed.”.
- **02** When the source has headings, the agent prioritizes “Decision Flow / Quick Reference / Creation Process” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
## Running Rules
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source does not require a stable slash command. After installation, invoke the skill by name and describe the task.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files, run shell commands.
Start with a small task and check whether the result follows “Decision Flow / Quick Reference / Creation Process”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: agent-customization
description: **WORKFLOW SKILL** — Create, update, review, fix, or debug VS Code agent customization files (.i…
category: documentation
source: microsoft/vscode
---
# agent-customization
## When to use
- **WORKFLOW SKILL** — Create, update, review, fix, or debug VS Code agent customization files (.instructions.md, .promp…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “Decision Flow / Quick Reference / Creation Process” and keep inference separate from source facts.
- read files, write/modify files, run shell commands; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "agent-customization" {
input -> user goal + target files + boundaries + acceptance criteria
context -> Decision Flow / Quick Reference / Creation Process
rules -> SKILL.md triggers / order / output contract
runtime -> no special runtime | read files, write/modify files, run shell commands | mostly runs locally
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} Agent Customization
Decision Flow
| Primitive | When to Use |
|---|---|
| agent 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 |
| Hooks | Deterministic shell commands at agent lifecycle points (block tools, auto-format, inject context) |
| 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. If the references are not enough, load the official documentation links for each primitive.
| Type | File | Location | Reference |
|---|---|---|---|
| agent instructions | copilot-instructions.md, AGENTS.md |
.github/ or root |
Link |
| File Instructions | *.instructions.md |
.github/instructions/ |
Link |
| Prompts | *.prompt.md |
.github/prompts/ |
Link |
| Hooks | *.json |
.github/hooks/ |
Link |
| Custom Agents | *.agent.md |
.github/agents/ |
Link |
| Skills | 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
descriptionis 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. Hooks can be defined in standalone .json files (see hooks reference) or inline in custom agent frontmatter via the hooks attribute (see agents 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.
Decide Fit First
Design Intent
How To Use It
Boundaries And Review