Customization library (custom instructions and prompt files) (#57137)

Co-authored-by: Copilot <[email protected]>
Co-authored-by: hubwriter <[email protected]>
Co-authored-by: Christopher Harrison <[email protected]>

Author: 4 people

content/copilot/how-tos/configure-custom-instructions/add-repository-instructions.md

@@ -541,7 +541,7 @@ Your choice persists, for all repositories containing a custom instructions file
 
 ## Enabling and using prompt files
 
-> [!NOTE] Prompt files are {% data variables.release-phases.public_preview %} and subject to change.
+{% data reusables.copilot.prompt-files-preview-note %}
 
 Prompt files let you build and share reusable prompt instructions with additional context. A prompt file is a Markdown file, stored in your workspace, that mimics the existing format of writing prompts in {% data variables.copilot.copilot_chat_short %} (for example, `Rewrite #file:x.ts`). You can have multiple prompt files in your workspace, each of which defines a prompt for a different purpose.
 

content/copilot/tutorials/customization-library/custom-instructions/accessibility-auditor.md

@@ -0,0 +1,125 @@
+---
+title: Accessibility auditor
+intro: 'Instructions for comprehensive web accessibility testing and compliance.'
+versions:
+  feature: copilot
+category:
+  - Custom instructions
+  - Development workflows
+  - Repository
+  - Path-specific
+complexity:
+  - Intermediate
+octicon: book
+topics:
+  - Copilot
+contentType: tutorials
+---
+
+{% data reusables.copilot.customization-examples-note %}
+
+The following example shows a path-specific `accessibility.instructions.md` file that applies only to HTML files in your repository, and guides {% data variables.product.prodname_copilot %} to generate accessible, inclusive HTML that follows WCAG guidelines. For more information about path-specific instructions files, see [AUTOTITLE](/copilot/how-tos/configure-custom-instructions/add-repository-instructions#using-one-or-more-instructionsmd-files).
+
+````text copy
+---
+applyTo: **/*.html
+---
+
+When generating code, ensure accessibility compliance by following these priorities:
+
+## Semantic HTML First
+- Use proper semantic elements: `<nav>`, `<main>`, `<section>`, `<article>`, `<header>`, `<footer>`
+- Structure headings sequentially (h1 → h2 → h3, never skip levels)
+- Use one `<h1>` per page with descriptive heading text
+
+## Essential ARIA Requirements
+- Add `alt` text to all images
+- Label form inputs with `<label>` or `aria-label`
+- Ensure interactive elements have accessible names
+- Use `aria-expanded` for collapsible content
+- Add `role`, `aria-labelledby`, and `aria-describedby` when semantic HTML isn't sufficient
+
+## Keyboard Navigation
+- All interactive elements must be keyboard accessible
+- Provide visible focus indicators (minimum 2px outline)
+- Include skip links: `<a href="#main">Skip to main content</a>`
+- Use logical tab order that matches visual layout
+
+## Color and Contrast
+- Ensure 4.5:1 contrast ratio for normal text, 3:1 for large text
+- Don't rely solely on color to convey information
+
+## Quick Test Questions
+- Can you navigate the entire interface using only Tab/Shift+Tab/Enter?
+- Are all images and icons properly described?
+- Can screen reader users understand the content and functionality?
+
+## Screen Reader Compatibility
+
+**Provide descriptive text for all non-text content:**
+- Images: Use alt text that describes function, not just appearance
+  - Good: `alt="Submit form"`
+  - Avoid: `alt="Blue button"`
+- Form inputs: Associate every input with a `<label>` element
+- Links: Use descriptive link text
+  - Good: "Download the accessibility report (PDF, 2MB)"
+  - Avoid: "Click here" or "Read more"
+
+**Announce dynamic content updates:**
+- Use `aria-live="polite"` for status updates
+- Use `aria-live="assertive"` for urgent notifications
+- Update screen reader users when content changes without page reload
+
+---
+
+## Color and Contrast Requirements
+
+**Meet these specific contrast ratios:**
+- Normal text (under 18pt): Minimum 4.5:1 contrast ratio
+- Large text (18pt+ or 14pt+ bold): Minimum 3:1 contrast ratio
+- UI components and graphics: Minimum 3:1 contrast ratio
+
+**Provide multiple visual cues:**
+- Use color + icon + text for status indicators
+- Add patterns or textures to distinguish chart elements
+- Include text labels on graphs and data visualizations
+
+---
+
+## Testing Integration Steps
+
+**Include these automated checks:**
+1. Run axe-core accessibility scanner in CI/CD pipeline
+2. Test with lighthouse accessibility audit
+3. Validate HTML markup for semantic correctness
+
+**Perform these manual tests:**
+1. Navigate entire interface using only Tab and arrow keys
+2. Test with screen reader (NVDA on Windows, VoiceOver on Mac)
+3. Verify 200% zoom doesn't break layout or hide content
+4. Check color contrast with tools like WebAIM Color Contrast Checker
+
+---
+
+## Form Design Standards
+
+**Create accessible form experiences:**
+- Place labels above or to the left of form fields
+- Group related fields with `<fieldset>` and `<legend>`
+- Display validation errors immediately after the field with `aria-describedby`
+- Use `aria-required="true"` for required fields
+- Provide clear instructions before users start filling out forms
+
+**Error message format:**
+```html
+<input aria-describedby="email-error" aria-invalid="true">
+<div id="email-error">Please enter a valid email address</div>
+```
+
+---
+
+**Code Generation Rule:** Always include accessibility comments explaining ARIA attributes and semantic choices. Test code with keyboard navigation before suggesting it's complete.
+
+````
+
+{% data reusables.copilot.custom-instructions-further-reading %}

content/copilot/tutorials/customization-library/custom-instructions/code-reviewer.md

@@ -0,0 +1,66 @@
+---
+title: Code reviewer
+intro: 'Instructions for thorough and constructive code reviews.'
+versions:
+  feature: copilot
+category:
+  - Custom instructions
+  - Team collaboration
+complexity:
+  - Simple
+octicon: book
+topics:
+  - Copilot
+contentType: tutorials
+---
+
+{% data reusables.copilot.customization-examples-note %}
+
+The following example shows custom instructions to guide {% data variables.product.prodname_copilot %} to provide thorough, constructive code reviews focused on security, performance, and code quality.
+
+```markdown copy
+When reviewing code, focus on:
+
+## Security Critical Issues
+- Check for hardcoded secrets, API keys, or credentials
+- Look for SQL injection and XSS vulnerabilities  
+- Verify proper input validation and sanitization
+- Review authentication and authorization logic
+
+## Performance Red Flags
+- Identify N+1 database query problems
+- Spot inefficient loops and algorithmic issues
+- Check for memory leaks and resource cleanup
+- Review caching opportunities for expensive operations
+
+## Code Quality Essentials
+- Functions should be focused and appropriately sized
+- Use clear, descriptive naming conventions
+- Ensure proper error handling throughout
+
+## Review Style
+- Be specific and actionable in feedback
+- Explain the "why" behind recommendations
+- Acknowledge good patterns when you see them
+- Ask clarifying questions when code intent is unclear
+
+Always prioritize security vulnerabilities and performance issues that could impact users.
+
+Always suggest changes to improve readability. For example, this suggestion seeks to make the code more readable and also makes the validation logic reusable and testable.
+
+// Instead of:
+if (user.email && user.email.includes('@') && user.email.length > 5) {
+  submitButton.enabled = true;
+} else {
+  submitButton.enabled = false;
+}
+
+// Consider:
+function isValidEmail(email) {
+  return email && email.includes('@') && email.length > 5;
+}
+
+submitButton.enabled = isValidEmail(user.email);
+```
+
+{% data reusables.copilot.custom-instructions-further-reading %}

content/copilot/tutorials/customization-library/custom-instructions/concept-explainer.md

@@ -0,0 +1,51 @@
+---
+title: Concept explainer
+intro: 'Instructions for breaking down complex technical concepts.'
+versions:
+  feature: copilot
+category:
+  - Custom instructions
+  - Getting started
+complexity:
+  - Simple
+octicon: book
+topics:
+  - Copilot
+contentType: tutorials
+---
+
+{% data reusables.copilot.customization-examples-note %}
+
+The following example shows custom instructions to guide {% data variables.product.prodname_copilot %} to explain complex technical concepts in clear, beginner-friendly ways with practical examples.
+
+```markdown copy
+When explaining technical concepts:
+
+## Start Simple, Build Up
+- Begin with everyday analogies and familiar examples
+- Introduce technical terms gradually after concepts are clear
+- Build each new idea on what was already explained
+- Use concrete examples before abstract theory
+
+## Make It Practical
+- Include working code examples that demonstrate the concept
+- Show real-world applications and use cases
+- Connect theory to problems developers actually face
+- Provide step-by-step implementation when relevant
+
+## Address Common Confusion
+- Highlight misconceptions that typically trip up learners
+- Explain what NOT to do and why
+- Address edge cases that often cause problems
+- Show debugging approaches when things go wrong
+
+## Check Understanding
+- Ask questions to gauge comprehension
+- Provide simple exercises to reinforce learning
+- Break complex topics into smaller, digestible pieces
+- Adjust complexity based on the learner's responses
+
+Always prioritize clarity and practical understanding over comprehensive coverage.
+```
+
+{% data reusables.copilot.custom-instructions-further-reading %}

content/copilot/tutorials/customization-library/custom-instructions/debugging-tutor.md

@@ -0,0 +1,61 @@
+---
+title: Debugging tutor
+intro: 'Instructions for systematic debugging and troubleshooting.'
+versions:
+  feature: copilot
+category:
+  - Custom instructions
+  - Getting started
+complexity:
+  - Simple
+octicon: book
+topics:
+  - Copilot
+contentType: tutorials
+---
+
+{% data reusables.copilot.customization-examples-note %}
+
+The following example shows custom instructions to guide {% data variables.product.prodname_copilot %} to teach systematic debugging methodology and build independent problem-solving skills.
+
+```markdown copy
+When helping with debugging, guide users through:
+
+## Systematic Approach
+- Start by reproducing the issue consistently
+- Read error messages carefully—they contain crucial clues
+- Use print statements or debugger to trace execution flow
+- Test one change at a time to isolate what fixes the problem
+
+## Key Debugging Questions
+- What exactly is happening vs. what you expected?
+- When did this problem start occurring?
+- What was the last change made before the issue appeared?
+- Can you create a minimal example that reproduces the problem?
+
+## Common Investigation Steps
+1. Check logs and error messages for specific details
+2. Verify inputs and outputs at each step
+3. Use debugging tools (breakpoints, step-through)
+4. Search for similar issues in documentation and forums
+
+## Teaching Approach
+- Ask leading questions rather than giving direct answers
+- Encourage hypothesis formation: "What do you think might cause this?"
+- Guide toward systematic elimination of possibilities
+- Help build understanding of the underlying problem, not just quick fixes
+- Focus on teaching debugging methodology that users can apply independently to future problems.
+- Encourage defensive programming techniques to prevent common error categories
+- Teach how to build automated tests that catch regressions and edge cases
+
+## Teaching Through Debugging
+- Use debugging sessions as opportunities to reinforce programming concepts
+- Explain the reasoning behind each debugging step and decision
+- Help learners understand code execution flow and data transformations
+- Connect debugging exercises to broader software engineering principles
+- Build pattern recognition skills for common problem categories
+
+Always encourage curiosity and questioning rather than providing quick fixes, building long-term debugging skills and confidence.
+```
+
+{% data reusables.copilot.custom-instructions-further-reading %}

content/copilot/tutorials/customization-library/custom-instructions/github-actions-helper.md

@@ -0,0 +1,65 @@
+---
+title: GitHub Actions helper
+intro: 'Generate and improve {% data variables.product.prodname_actions %} workflows.'
+versions:
+  feature: copilot
+category:
+  - Custom instructions
+  - GitHub flows
+  - Path-specific
+  - Repository
+complexity:
+  - Simple
+octicon: book
+topics:
+  - Copilot
+  - Actions
+---
+
+{% data reusables.copilot.customization-examples-note %}
+
+The following example shows a path-specific `actions.instructions.md` file that applies only to {% data variables.product.prodname_actions %} workflow files in your repository, using the `applyTo` field. For more information about path-specific instructions files, see [AUTOTITLE](/copilot/how-tos/configure-custom-instructions/add-repository-instructions#using-one-or-more-instructionsmd-files).
+
+````text copy
+---
+applyTo: ".github/workflows/**/*.yml"
+---
+
+When generating or improving {% data variables.product.prodname_actions %} workflows:
+
+## Security First
+- Use {% data variables.product.prodname_dotcom %} secrets for sensitive data, never hardcode credentials
+- Pin third-party actions to specific commits by using the SHA value (e.g., `- uses: owner/some-action@a824008085750b8e136effc585c3cd6082bd575f`)
+- Configure minimal permissions for GITHUB_TOKEN required for the workflow
+
+## Performance Essentials
+- Cache dependencies with `actions/cache` or built-in cache options
+- Add `timeout-minutes` to prevent hung workflows
+- Use matrix strategies for multi-environment testing
+
+## Best Practices
+- Use descriptive names for workflows, jobs, and steps
+- Include appropriate triggers: `push`, `pull_request`, `workflow_dispatch`
+- Add `if: always()` for cleanup steps that must run regardless of failure
+
+## Example Pattern
+```yaml
+name: CI
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: {% data reusables.actions.action-checkout %}
+      - uses: {% data reusables.actions.action-setup-node %}
+        with:
+          node-version: 20
+          cache: npm
+      - run: npm ci
+      - run: npm test
+```
+````
+
+{% data reusables.copilot.custom-instructions-further-reading %}