Copilot instructions

1---
2applyTo:
3  - ".github/instructions/**/*.instructions.md"
4---
5 
6# Instruction File Format Guide
7 
8This document describes the format and guidelines for creating custom instruction files for GitHub Copilot in the PowerShell repository.
9 
10## File Naming Convention
11 
12All instruction files must use the `.instructions.md` suffix:
13- ✅ Correct: `build-checkout-prerequisites.instructions.md`
14- ✅ Correct: `start-psbuild-basics.instructions.md`
15- ❌ Incorrect: `build-guide.md`
16- ❌ Incorrect: `instructions.md`
17 
18## Required Frontmatter
19 
20Every instruction file must start with YAML frontmatter containing an `applyTo` section:
21 
22```yaml
23---
24applyTo:
25  - "path/to/files/**/*.ext"
26  - "specific-file.ext"
27---
28```
29 
30### applyTo Patterns
31 
32Specify which files or directories these instructions apply to:
33 
34**For workflow files:**
35```yaml
36applyTo:
37  - ".github/**/*.yml"
38  - ".github/**/*.yaml"
39```
40 
41**For build scripts:**
42```yaml
43applyTo:
44  - "build.psm1"
45  - "tools/ci.psm1"
46```
47 
48**For multiple contexts:**
49```yaml
50applyTo:
51  - "build.psm1"
52  - "tools/**/*.psm1"
53  - ".github/**/*.yml"
54```
55 
56## Content Structure
57 
58### 1. Clear Title
59 
60Use a descriptive H1 heading after the frontmatter:
61 
62```markdown
63# Build Configuration Guide
64```
65 
66### 2. Purpose or Overview
67 
68Start with a brief explanation of what the instructions cover:
69 
70```markdown
71## Purpose
72 
73This guide explains how to configure PowerShell builds for different scenarios.
74```
75 
76### 3. Actionable Content
77 
78Provide clear, actionable guidance:
79 
80**✅ Good - Specific and actionable:**
81```markdown
82## Default Usage
83 
84Use `Start-PSBuild` with no parameters for testing:
85 
86```powershell
87Import-Module ./tools/ci.psm1
88Start-PSBuild
89```
90```
91 
92**❌ Bad - Vague and unclear:**
93```markdown
94## Usage
95 
96You can use Start-PSBuild to build stuff.
97```
98 
99### 4. Code Examples
100 
101Include working code examples with proper syntax highlighting:
102 
103```markdown
104```yaml
105- name: Build PowerShell
106  shell: pwsh
107  run: |
108    Import-Module ./tools/ci.psm1
109    Start-PSBuild
110```
111```
112 
113### 5. Context and Rationale
114 
115Explain why things are done a certain way:
116 
117```markdown
118**Why fetch-depth: 1000?**
119- The build system needs Git history for version calculation
120- Shallow clones would break versioning logic
121```
122 
123## Best Practices
124 
125### Be Concise
126 
127- Focus on essential information
128- Remove redundant explanations
129- Use bullet points for lists
130 
131### Be Specific
132 
133- Provide exact commands and parameters
134- Include file paths and line numbers when relevant
135- Show concrete examples, not abstract concepts
136 
137### Avoid Duplication
138 
139- Don't repeat information from other instruction files
140- Reference other files when appropriate
141- Keep each file focused on one topic
142 
143### Use Proper Formatting
144 
145**Headers:**
146- Use H1 (`#`) for the main title
147- Use H2 (`##`) for major sections
148- Use H3 (`###`) for subsections
149 
150**Code blocks:**
151- Always specify the language: ` ```yaml `, ` ```powershell `, ` ```bash `
152- Keep examples short and focused
153- Test examples before including them
154 
155**Lists:**
156- Use `-` for unordered lists
157- Use `1.` for ordered lists
158- Keep list items concise
159 
160## Example Structure
161 
162```markdown
163---
164applyTo:
165  - "relevant/files/**/*.ext"
166---
167 
168# Title of Instructions
169 
170Brief description of what these instructions cover.
171 
172## Section 1
173 
174Content with examples.
175 
176```language
177code example
178```
179 
180## Section 2
181 
182More specific guidance.
183 
184### Subsection
185 
186Detailed information when needed.
187 
188## Best Practices
189 
190- Actionable tip 1
191- Actionable tip 2
192```
193 
194## Maintaining Instructions
195 
196### When to Create a New File
197 
198Create a new instruction file when:
199- Covering a distinct topic not addressed elsewhere
200- The content is substantial enough to warrant its own file
201- The `applyTo` scope is different from existing files
202 
203### When to Update an Existing File
204 
205Update an existing file when:
206- Information is outdated
207- New best practices emerge
208- Examples need correction
209 
210### When to Merge or Delete
211 
212Merge or delete files when:
213- Content is duplicated across multiple files
214- A file is too small to be useful standalone
215- Information is no longer relevant
216 
217## Reference
218 
219For more details, see:
220- [GitHub Copilot Custom Instructions Documentation](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions)
221 
222```