代理定制
- 作者仓库星标 9,940
- 作者仓库 vscode-copilot-chat
- 领域
- 文档
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @microsoft · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# 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 |
| 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 |
|------|------|----------|-----------|
| Workspace Instructions | `copilot-instructions.md`, `AGENTS.md` | `.github/` or root | [Link](./references/workspace-instructions.md) |
| File Instructions | `*.instructions.md` | `.github/instructions/` | [Link](./references/instructions.md) |
| Prompts | `*.prompt.md` | `.github/prompts/` | [Link](./references/prompts.md) |
| Hooks | `*.json` | `.github/hooks/` | [Link](./references/hooks.md) |
| Custom Agents | `*.agent.md` | `.github/agents/` | [Link](./references/agents.md) |
| Skills | `SKILL.md` | `.github/skills/<name>/`, `.agents/skills/<name>/`, `.claude/skills/<name>/` | [Link](./references/skills.md) |
**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](./references/hooks.md).
## 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.
章节与文件索引
按说明文件中的顺序排列。
决策流程
快速参考
创作过程
1. 确定范围
2. 选择正确的原语
文件/命令 -> applyTo · description · copilot-instructions.md · AGENTS.md · .github/ · *.instructions.md · .github/instructions/ · *.prompt.md
内容校验值 -> 258f0106c7aa
当前原文的自动摘译,尚未人工审校。
决策流程
原始 · 何时使用工作区指令 · 始终在线,适用于项目中的任何位置 文件指令 · 通过
applyTo模式显式显示,或通过descriptionMCP 按需显示 · 集成外部系统、API 或数据挂钩 · 代理生命周期点的确定性 shell 命令(块工具、自动格式化、注入上下文)快速参考
请参阅参考文档以获取模板、领域示例、高级 frontmatter 选项、资产组织、反模式和创建清单。如果参考文献不够,请加载每个原语的官方文档链接。类型·文件·位置·参考工作区说明·
copilot-instructions.md、AGENTS.md·.github/或根·链接文件说明·*.instructions.md·.github/instructions/·链接创作过程
如果您需要探索或验证代码库中的模式,请使用只读子代理。如果提问工具可用,请使用它来采访用户并澄清需求。创建任何自定义文件时请按照以下步骤操作。
1. 确定范围
询问用户想要在哪里进行自定义: 工作空间:用于特定于项目、团队共享的自定义 →
.github/文件夹 用户配置文件:用于个人、跨工作空间的自定义 →{{VSCODE_USER_PROMPTS_FOLDER}}/2. 选择正确的原语
使用上面的决策流程根据用户的需要选择适当的文件类型。