vscode-copilot-instructions

# VSCode Copilot Custom Instructions & Prompt Files Expert guidance for creating and managing VSCode Copilot customization files including custom instructions, prompt files, and agent configurations. ## When to Use This Skill Activate this skill when: - Creating `.github/copilot-instructions.md` files - Building `.instructions.md` files with applyTo patterns - Setting up `AGENTS.md` configurations - Creating `.prompt.md` reusable prompts - Configuring YAML frontmatter for any of these file types - Understanding variable syntax (`${variable}`) - Referencing tools (`#tool:toolName`) or files in instructions - Troubleshooting instruction file activation issues - Sharing custom instructions across teams or repositories ## Quick Overview: File Types ### 1. `.github/copilot-instructions.md` **Always-on workspace instructions** — Applied automatically to all chat requests in the workspace. **When to use**: General coding guidelines, team conventions, project-specific rules that apply throughout the project. **Location**: `.github/copilot-instructions.md` at workspace root **Example**: ```markdown # Project Guidelines - Use TypeScript for all new code - Follow functional programming patterns - Write tests using Jest - API responses must use our standard error format ``` 📄 **Complete Guide**: [references/copilot-instructions-guide.md](references/copilot-instructions-guide.md) --- ### 2. `.instructions.md` Files **Conditional, targeted instructions** — Apply to specific file types, locations, or tasks using `applyTo` glob patterns. **When to use**: Language-specific guidelines, framework-specific patterns, file-type-specific rules. **Location**: `.github/instructions/` folder or user profile **Example**: ```markdown --- name: python-coding-standards description: Python coding standards and best practices applyTo: "**/*.py" --- # Python Standards - Follow PEP 8 style guide - Use type hints for all functions - Write docstrings using Google style ``` 📄 **Complete Guide**: [references/instructions-files-guide.md](references/instructions-files-guide.md) --- ### 3. `AGENTS.md` File **Multi-agent workspace instructions** — Useful when working with multiple AI agents, applied automatically like copilot-instructions.md. **When to use**: When you work with multiple AI coding assistants and want unified instructions. **Location**: Workspace root, or subfolders (experimental) **Example**: ```markdown # Agent Guidelines All agents working in this codebase must: - Never modify files in the `legacy/` directory - Always run tests before committing - Use the project's error handling utilities ``` 📄 **Complete Guide**: [references/agents-md-guide.md](references/agents-md-guide.md) --- ### 4. `.prompt.md` Files **Reusable, on-demand prompts** — Triggered via `/command` in chat for specific development tasks. **When to use**: Standardized workflows, code generation templates, review checklists, common development tasks. **Location**: `.github/prompts/` folder or user profile **Example**: ```markdown --- name: create-react-component description: Generate a React component with TypeScript and tests argument-hint: component-name agent: edit --- # Create React Component Create a new React component named ${input:componentName} with: 1. TypeScript interface for props 2. Function component implementation 3. Jest test file with basic tests 4. Storybook story file Follow our component patterns in [docs/component-guidelines.md](docs/component-guidelines.md). ``` 📄 **Complete Guide**: [references/prompt-files-guide.md](references/prompt-files-guide.md) --- ## Decision Tree: Which File Type? ``` Do you want instructions that apply automatically? ├─ YES → Always-on for entire workspace? │ ├─ YES → Use .github/copilot-instructions.md │ └─ NO → Apply to specific files/patterns? │ └─ Use .instructions.md with applyTo pattern │ └─ NO → Want to trigger on-demand? └─ Use .prompt.md file (invoked via /command) ``` **Also consider**: Use `AGENTS.md` if working with multiple AI agents simultaneously. --- ## Common Elements Across All File Types ### YAML Frontmatter (Optional but Recommended) All file types support YAML frontmatter for metadata: ```yaml --- name: file-name-slug description: What this file does applyTo: "**/*.py" # .instructions.md only agent: edit # .prompt.md only tools: [githubRepo, files] # .prompt.md only --- ``` ### Variable Syntax Reference dynamic values in file bodies: ```markdown - `${workspaceFolder}` — Workspace root path - `${file}` — Currently open file path - `${selection}` — Selected text - `${input:variableName}` — User input from chat - `${input:variableName:placeholder}` — With placeholder hint ``` 📄 **Complete Reference**: [references/variables-and-references.md](references/variables-and-references.md) ### Tool References Reference agent tools using special syntax: ```markdown Use #tool:githubRepo to search the repository. Use #tool:files to read workspace files. ``` ### File References Link to other workspace files using relative Markdown links: ```markdown Follow the patterns in [docs/api-guide.md](docs/api-guide.md). See [scripts/validate.py](scripts/validate.py) for examples. ``` --- ## Reference Documentation All detailed guides are in the `references/` folder: - [**Copilot Instructions Guide**](references/copilot-instructions-guide.md) — `.github/copilot-instructions.md` complete reference - [**Instructions Files Guide**](references/instructions-files-guide.md) — `.instructions.md` with applyTo patterns - [**AGENTS.md Guide**](references/agents-md-guide.md) — Multi-agent workspace configuration - [**Prompt Files Guide**](references/prompt-files-guide.md) — `.prompt.md` reusable prompts - [**Variables & References**](references/variables-and-references.md) — All variable syntax and file referencing - [**Best Practices**](references/best-practices.md) — Writing effective instructions - [**Troubleshooting**](references/troubleshooting.md) — Common issues and solutions --- ## Template Files Ready-to-use templates in `assets/templates/`: - [copilot-instructions.template.md](assets/templates/copilot-instructions.template.md) - [instructions-file.template.md](assets/templates/instructions-file.template.md) - [agents.template.md](assets/templates/agents.template.md) - [prompt-file.template.md](assets/templates/prompt-file.template.md) --- ## Quick Start Workflows ### Creating Always-On Instructions ```bash # 1. Create .github directory if needed mkdir -p .github # 2. Create copilot-instructions.md code .github/copilot-instructions.md # 3. Add your guidelines # 4. Enable in settings: github.copilot.chat.codeGeneration.useInstructionFiles ``` ### Creating Conditional Instructions ```bash # 1. Create instructions directory mkdir -p .github/instructions # 2. Create instruction file code .github/instructions/my-rules.instructions.md # 3. Add YAML frontmatter with applyTo pattern # 4. Enable: chat.includeApplyingInstructions ``` ### Creating Reusable Prompts ```bash # 1. Create prompts directory mkdir -p .github/prompts # 2. Create prompt file code .github/prompts/my-task.prompt.md # 3. Use in chat: /my-task ``` --- ## Settings to Enable Ensure these VS Code settings are enabled: ```json { // Enable copilot-instructions.md "github.copilot.chat.codeGeneration.useInstructionFiles": true, // Enable .instructions.md with applyTo patterns "chat.includeApplyingInstructions": true, // Enable AGENTS.md "chat.useAgentsMdFile": true, // Enable nested AGENTS.md in subfolders (experimental) "chat.useNestedAgentsMdFiles": false, // Show prompts as recommendations "chat.promptFilesRecommendations": true } ``` --- ## Key Best Practices ✅ **Keep Instructions Concise**: Each instruction should be a single, clear statement ✅ **Use Specific Examples**: Show code examples of what you want ✅ **Reference, Don't Duplicate**: Use Markdown links to existing docs ✅ **Test Activation**: Verify instructions trigger correctly ✅ **Layer Appropriately**: Use the right file type for the right scope ❌ **Avoid Vague Guidance**: "Write good code" → Instead: "Use functional components with TypeScript interfaces" ❌ **Don't Overload**: Too many instructions reduce effectiveness ❌ **Don't Forget Settings**: Instructions won't work without proper VS Code settings 📄 **Full Best Practices**: [references/best-practices.md](references/best-practices.md) --- ## Troubleshooting **Instructions not applying?** 1. Check the file is in the correct location 2. Verify the relevant setting is enabled 3. Check YAML frontmatter syntax 4. For `.instructions.md`: verify `applyTo` glob pattern matches 5. View diagnostics: Right-click in Chat → Diagnostics 📄 **Full Troubleshooting Guide**: [references/troubleshooting.md](references/troubleshooting.md) --- ## Example Use Cases ### Use Case 1: Team Coding Standards **Solution**: `.github/copilot-instructions.md` with always-on guidelines ### Use Case 2: Python-Specific Rules **Solution**: `.instructions.md` with `applyTo: "**/*.py"` ### Use Case 3: Generate API Endpoint **Solution**: `.prompt.md` with `/create-endpoint` command ### Use Case 4: Multiple AI Assistants **Solution**: `AGENTS.md` at workspace root --- ## Community Resources - [Official VSCode Docs](https://code.visualstudio.com/docs/copilot/customization/custom-instructions) - [Prompt Files Docs](https://code.visualstudio.com/docs/copilot/customization/prompt-files) - [Awesome Copilot Repository](https://github.com/github/awesome-copilot/tree/main) — Community examples --- **Remember**: Instruction files are most effective when they're specific, actionable, and well-organized. Start simple and iterate based on what works for your team.