AgentSkillsCN

copilot-custom-instructions

如何编写并组织 VS Code Copilot 自定义指令（.instructions.md）以及代理技能（SKILL.md）。当您需要创建、编辑、重新组织或调试自定义指令文件或技能文件时，或者在被问及 applyTo 全局匹配语法时，请使用本指南。

SKILL.md
--- frontmatter
name: copilot-custom-instructions
description: "How to write and organize VS Code Copilot custom instructions (.instructions.md) and agent skills (SKILL.md). Use when creating, editing, reorganizing, or debugging custom instruction or skill files, or when asked about applyTo glob syntax."

Writing Custom Instructions & Agent Skills\n\n> ⚠️ Structural rules: Do NOT rename, move, or delete instruction/skill files without updating the preamble table in copilot-instructions.md. Run npm run lint:docs to verify all cross-references. See pitfall #11.

This skill documents the file formats and conventions for VS Code Copilot custom instructions and agent skills, so you don't need to look up external documentation.

.instructions.md Files (Scoped Instructions)

File Format

yaml
---
name: "Display Name"              # optional, defaults to filename
description: "Short description"  # optional
applyTo: "**/*.py"               # optional glob; if omitted, manual-attach only
---

# Markdown body with instructions

applyTo Glob Syntax

  • •Single pattern: "src/services/**"
  • •Multiple patterns (comma-separated in a single string): "**/*.ts,**/*.tsx"
  • •Match all files: "**"
  • •If omitted, the instructions file is not applied automatically (user must attach it manually)
  • •Paths are relative to the workspace root

Supported glob patterns:

PatternMeaning
*All files in the current directory
** or **/*All files in all directories
*.pyAll .py files in the current directory
**/*.pyRecursively match all .py files
src/**/*.pyRecursively match .py files in src/

Storage Location

  • •Workspace-level: .github/instructions/<name>.instructions.md
  • •User-level: VS Code profile folder (syncable via Settings Sync)
  • •Additional folders: Configurable via chat.instructionsFilesLocations setting

Relevant Settings

SettingPurpose
github.copilot.chat.codeGeneration.useInstructionFilesEnable .instructions.md files
chat.includeApplyingInstructionsAuto-apply instructions with matching applyTo

When to Use

  • •General coding standards and conventions
  • •Language or framework-specific rules
  • •File-pattern-specific guidelines (e.g., all test files, all Vue components)
  • •Always-on or glob-matched context

SKILL.md Files (Agent Skills)

File Format

yaml
---
name: my-skill-name              # required, lowercase with hyphens
description: "What this skill does and WHEN Copilot should use it"  # required
license: "MIT"                   # optional
---

# Markdown body with detailed instructions, steps, examples

Key Differences from Instructions

AspectCustom InstructionsAgent Skills
ScopeAlways-on or glob-matchedLoaded on-demand when relevant
ComplexitySimple markdown guidelinesFolders with SKILL.md + optional scripts/resources
Use caseGeneral coding standardsSpecialized, repeatable tasks
SelectionAutomatic by applyTo globCopilot decides based on description field

Storage Locations

  • •Project skills: .github/skills/<skill-name>/SKILL.md
  • •Personal skills: ~/.copilot/skills/<skill-name>/SKILL.md

The file must be named SKILL.md exactly. Each skill lives in its own directory whose name should be lowercase with hyphens and typically match the name frontmatter field.

How Copilot Uses Skills

  1. •Copilot reads the description field of each available skill
  2. •Based on the user's prompt, it decides which skills are relevant
  3. •When chosen, the full SKILL.md content is injected into the agent's context
  4. •The agent follows those instructions using any scripts/examples in the skill's directory

Relevant Settings

SettingPurpose
chat.useAgentSkillsEnable agent skills loading

When to Use

  • •Step-by-step recipes for specific tasks (e.g., "add a new API endpoint")
  • •Specialized debugging workflows
  • •Complex multi-file scaffolding patterns
  • •Any task where detailed, on-demand instructions are more appropriate than always-loaded context

Root copilot-instructions.md

The file at .github/copilot-instructions.md is always loaded for all chat requests in the workspace. Use it for:

  • •Project overview and architecture
  • •Critical invariants that apply everywhere
  • •Build/run commands and common issues

Keep it focused — move file-specific details to scoped .instructions.md files.

Requires github.copilot.chat.codeGeneration.useInstructionFiles to be enabled.

Debugging

  • •VS Code: Right-click the Chat view → "Diagnostics" to see all loaded instruction files
  • •applyTo not matching?: Check that the glob pattern matches the file you're working on (relative to workspace root)
  • •Skill not loading?: Check that the description field clearly describes when it should be used