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

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: hubwriter <hubwriter@github.com>
Co-authored-by: Christopher Harrison <geektrainer@github.com>

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 %}

content/copilot/tutorials/customization-library/custom-instructions/index.md

@@ -0,0 +1,20 @@
+---
+title: Custom instructions
+intro: 'Discover a curated collection of custom instructions to enhance your {% data variables.product.prodname_copilot %} experience.'
+allowTitleToDifferFromFilename: true
+versions:
+  feature: copilot
+topics:
+  - Copilot
+children:
+  - /your-first-custom-instructions
+  - /concept-explainer
+  - /debugging-tutor
+  - /code-reviewer
+  - /github-actions-helper
+  - /pull-request-assistant
+  - /issue-manager
+  - /accessibility-auditor
+  - /testing-automation
+contentType: tutorials
+---

content/copilot/tutorials/customization-library/custom-instructions/issue-manager.md

@@ -0,0 +1,60 @@
+---
+title: Issue manager
+intro: 'Create well-structured issues and responses.'
+versions:
+  feature: copilot
+category:
+  - Custom instructions
+  - GitHub flows
+complexity:
+  - Simple
+octicon: book
+topics:
+  - Copilot
+  - Issues
+---
+
+{% data reusables.copilot.customization-examples-note %}
+
+The following example shows custom instructions to guide {% data variables.product.prodname_copilot %} to create well-structured, actionable {% data variables.product.prodname_dotcom %} issues and provide effective issue management.
+
+```markdown copy
+When creating or managing {% data variables.product.prodname_dotcom %} issues:
+
+## Bug Report Essentials
+**Description**: Clear, concise summary of the problem
+
+**Steps to Reproduce**: Numbered list of exact actions that cause the issue
+
+**Expected vs Actual Behavior**: What should happen vs what actually happens
+
+**Environment**: OS, browser/client, app version, relevant dependencies
+
+**Additional Context**: Screenshots, error logs, or stack traces
+
+## Feature Request Structure
+**Problem**: What specific problem does this solve?
+
+**Proposed Solution**: Brief description of the suggested approach
+
+**Use Cases**: 2-3 concrete examples of when this would be valuable
+
+**Success Criteria**: How to measure if the feature works
+
+## Issue Management Best Practices
+- Use clear, descriptive titles that summarize the request
+- Apply appropriate labels: bug/feature, priority level, component areas
+- Ask clarifying questions when details are missing
+- Link related issues using #number syntax
+- Provide specific next steps and realistic timelines
+
+## Key Response Guidelines
+- Request reproduction steps for unclear bugs
+- Ask for screenshots/logs when visual issues are reported  
+- Explain technical concepts clearly for non-technical users
+- Update issue status regularly with progress information
+
+Focus on making issues actionable and easy for contributors to understand.
+```
+
+{% data reusables.copilot.custom-instructions-further-reading %}

content/copilot/tutorials/customization-library/custom-instructions/pull-request-assistant.md

@@ -0,0 +1,114 @@
+---
+title: Pull request assistant
+intro: 'Generate comprehensive pull request descriptions and reviews.'
+versions:
+  feature: copilot
+category:
+  - Custom instructions
+  - GitHub flows
+complexity:
+  - Simple
+octicon: book
+topics:
+  - Copilot
+  - Pull requests
+---
+
+{% data reusables.copilot.customization-examples-note %}
+
+The following example shows custom instructions to guide {% data variables.product.prodname_copilot %} to create detailed pull request descriptions and provide constructive code reviews.
+
+```markdown copy
+When creating pull request descriptions or reviewing PRs:
+
+## PR Description Template
+**What changed**
+- Clear summary of modifications and affected components
+- Link to related issues or tickets
+
+**Why**
+- Business context and requirements
+- Technical reasoning for approach taken
+
+**Testing**
+- [ ] Unit tests pass and cover new functionality
+- [ ] Manual testing completed for user-facing changes  
+- [ ] Performance/security considerations addressed
+
+**Breaking Changes**
+- List any API changes or behavioral modifications
+- Include migration instructions if needed
+
+## Review Focus Areas
+- **Security**: Check for hardcoded secrets, input validation, auth issues
+- **Performance**: Look for database query problems, inefficient loops
+- **Testing**: Ensure adequate test coverage for new functionality
+- **Documentation**: Verify code comments and README updates
+
+## Review Style
+- Be specific and constructive in feedback
+- Acknowledge good patterns and solutions
+- Ask clarifying questions when code intent is unclear
+- Focus on maintainability and readability improvements
+- Always prioritize changes that improve security, performance, or user experience.
+- Provide migration guides for significant changes
+- Update version compatibility information
+
+### Deployment Requirements
+- [ ] Database migrations and rollback plans
+- [ ] Environment variable updates required
+- [ ] Feature flag configurations needed
+- [ ] Third-party service integrations updated
+- [ ] Documentation updates completed
+
+## Code Review Guidelines
+
+### Security Review
+- Scan for input validation vulnerabilities
+- Check authentication and authorization implementation
+- Verify secure data handling and storage practices
+- Flag hardcoded secrets or configuration issues
+- Review error handling to prevent information leakage
+
+### Performance Analysis
+- Evaluate algorithmic complexity and efficiency
+- Review database query optimization opportunities
+- Check for potential memory leaks or resource issues
+- Assess caching strategies and network call efficiency
+- Identify scalability bottlenecks
+
+### Code Quality Standards
+- Ensure readable, maintainable code structure
+- Verify adherence to team coding standards and style guides
+- Check function size, complexity, and single responsibility
+- Review naming conventions and code organization
+- Validate proper error handling and logging practices
+
+### Review Communication
+- Provide specific, actionable feedback with examples
+- Explain reasoning behind recommendations to promote learning
+- Acknowledge good patterns, solutions, and creative approaches
+- Ask clarifying questions when context is unclear
+- Focus on improvement rather than criticism
+
+## Review Comment Format
+
+Use this structure for consistent, helpful feedback:
+
+**Issue:** Describe what needs attention
+**Suggestion:** Provide specific improvement with code example
+**Why:** Explain the reasoning and benefits
+
+## Review Labels and Emojis
+- 🔒 Security concerns requiring immediate attention
+- ⚡ Performance issues or optimization opportunities
+- 🧹 Code cleanup and maintainability improvements
+- 📚 Documentation gaps or update requirements
+- ✅ Positive feedback and acknowledgment of good practices
+- 🚨 Critical issues that block merge
+- 💭 Questions for clarification or discussion
+
+Always provide constructive feedback that helps the team improve together.
+```
+
+{% data reusables.copilot.custom-instructions-further-reading %}

content/copilot/tutorials/customization-library/custom-instructions/testing-automation.md

@@ -0,0 +1,64 @@
+---
+title: Testing automation
+intro: 'File-specific instructions for writing unit tests.'
+versions:
+  feature: copilot
+category:
+  - Custom instructions
+  - Development workflows
+  - Path-specific
+  - Repository
+complexity:
+  - Advanced
+octicon: book
+topics:
+  - Copilot
+contentType: tutorials
+---
+
+{% data reusables.copilot.customization-examples-note %}
+
+This example shows a path-specifc `python-tests.instructions.md` file that applies only to Python test 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: "tests/**/*.py"
+---
+
+When writing Python tests:
+
+## Test Structure Essentials
+- Use pytest as the primary testing framework
+- Follow AAA pattern: Arrange, Act, Assert
+- Write descriptive test names that explain the behavior being tested
+- Keep tests focused on one specific behavior
+
+## Key Testing Practices
+- Use pytest fixtures for setup and teardown
+- Mock external dependencies (databases, APIs, file operations)
+- Use parameterized tests for testing multiple similar scenarios
+- Test edge cases and error conditions, not just happy paths
+
+## Example Test Pattern
+```python
+import pytest
+from unittest.mock import Mock, patch
+
+class TestUserService:
+    @pytest.fixture
+    def user_service(self):
+        return UserService()
+    
+    @pytest.mark.parametrize("invalid_email", ["", "invalid", "@test.com"])
+    def test_should_reject_invalid_emails(self, user_service, invalid_email):
+        with pytest.raises(ValueError, match="Invalid email"):
+            user_service.create_user({"email": invalid_email})
+    
+    @patch('src.user_service.email_validator')
+    def test_should_handle_validation_failure(self, mock_validator, user_service):
+        mock_validator.validate.side_effect = ConnectionError()
+        
+        with pytest.raises(ConnectionError):
+            user_service.create_user({"email": "test@example.com"})
+```
+````

content/copilot/tutorials/customization-library/custom-instructions/your-first-custom-instructions.md

@@ -0,0 +1,101 @@
+---
+title: Your first custom instructions
+intro: 'Create and test your first custom instruction with this simple example.'
+versions:
+  feature: copilot
+category:
+  - Custom instructions
+  - Getting started
+complexity:
+  - Simple
+octicon: book
+topics:
+  - Copilot
+---
+
+{% data reusables.copilot.customization-examples-note %}
+
+## About customizations
+
+You can customize {% data variables.product.prodname_copilot %}'s responses using two types of files:
+
+* **Custom instructions** provide ongoing guidance for how {% data variables.product.prodname_copilot %} should behave across all your interactions.
+* **Prompt files (public preview)** define reusable prompts for specific tasks that you can invoke when needed. Prompt files are only available in {% data variables.product.prodname_vscode_shortname %}. For an introductory example, see [AUTOTITLE](/copilot/tutorials/customization-library/prompt-files/your-first-prompt-file).
+
+While custom instructions help to add context to each AI workflow, prompt files let you add instructions to a specific chat interaction.
+
+Repository custom instructions are the most commonly used and supported, but you can also define personal and organization custom instructions, only for {% data variables.copilot.copilot_chat_dotcom %}. {% data reusables.copilot.repository-custom-instructions-types %}
+
+## Your first instructions
+
+Start with these core custom instructions that helps {% data variables.product.prodname_copilot %} understand your coding preferences.
+
+### Instructions on writing functions
+
+```markdown copy
+When writing functions, always:
+- Add descriptive JSDoc comments
+- Include input validation
+- Use early returns for error conditions
+- Add meaningful variable names
+- Include at least one example usage in comments
+```
+
+These instructions will change how {% data variables.product.prodname_copilot %} generates functions.
+
+## Test it out
+
+To quickly test out the difference that custom instructions can make, you can use personal custom instructions in {% data variables.copilot.copilot_chat_short %}'s immersive view.
+
+1. First, go to [github.com/copilot](https://github.com/copilot) and enter this prompt:
+
+    `Create a JavaScript function that calculates the area of a circle`
+
+    **Without custom instructions**, you might get:
+
+    ```javascript
+    function areaOfCircle(radius) {
+        if (typeof radius !== 'number' || radius < 0) {
+            throw new Error('Radius must be a non-negative number');
+        }
+        return Math.PI * radius * radius;
+    }
+    ```
+
+1. Now access your personal custom instructions by clicking on your profile picture in the bottom left of the page, then click **Personal instructions**. Paste the above instructions into the text box, then click **Save**.
+
+    Now enter the same prompt that you entered previously.
+
+    **With custom instructions**, you'll get something like:
+
+    ```javascript
+    /**
+     * Calculates the area of a circle given its radius.
+     *
+     * @param {number} radius - The radius of the circle. Must be a positive number.
+     * @returns {number|null} The area of the circle, or null if the input is invalid.
+     *
+     * @example
+     * // returns 78.53981633974483
+     * areaOfCircle(5);
+     *
+     * @example
+     * // returns null (invalid input)
+     * areaOfCircle(-2);
+     */
+    function areaOfCircle(radius) {
+      if (typeof radius !== "number" || isNaN(radius) || radius <= 0) {
+        // Invalid input: radius must be a positive number
+        return null;
+      }
+
+      const area = Math.PI * Math.pow(radius, 2);
+      return area;
+    }
+
+    // Example usage:
+    console.log(areaOfCircle(5));   // 78.53981633974483
+    console.log(areaOfCircle(-2));  // null
+    ```
+
+{% data reusables.copilot.custom-instructions-further-reading %}

content/copilot/tutorials/customization-library/index.md

@@ -0,0 +1,23 @@
+---
+title: Customization library
+intro: 'Discover a curated collection of customizations, including custom instructions and prompt files (VS Code only), to enhance your {% data variables.product.prodname_copilot %} experience.'
+allowTitleToDifferFromFilename: true
+versions:
+  feature: copilot
+topics:
+  - Copilot
+layout: category-landing
+sidebarLink:
+  text: All customizations
+  href: /copilot/tutorials/customization-library
+spotlight:
+  - article: /custom-instructions/your-first-custom-instructions
+    image: /assets/images/copilot-landing/generating_unit_tests.png
+  - article: /prompt-files/your-first-prompt-file
+    image: /assets/images/copilot-landing/improving_code_readability.png
+children:
+  - /custom-instructions
+  - /prompt-files
+contentType: tutorials
+---
+

content/copilot/tutorials/customization-library/prompt-files/create-readme.md

@@ -0,0 +1,76 @@
+---
+title: Create README
+intro: 'Generate comprehensive README files for your projects.'
+versions:
+  feature: copilot
+category:
+  - Prompt files
+  - Getting started
+complexity:
+  - Simple
+octicon: copilot
+topics:
+  - Copilot
+contentType: tutorials
+---
+
+{% data reusables.copilot.prompt-files-preview-note %}
+
+This prompt file creates professional, comprehensive README files by analyzing your entire project structure and codebase.
+
+## README generator prompt
+
+```text copy
+---
+mode: 'agent'
+description: 'Create a comprehensive README.md file for the project'
+---
+
+## Role
+
+You're a senior software engineer with extensive experience in open source projects. You create appealing, informative, and easy-to-read README files.
+
+## Task
+
+1. Review the entire project workspace and codebase
+2. Create a comprehensive README.md file with these essential sections:
+   - **What the project does**: Clear project title and description
+   - **Why the project is useful**: Key features and benefits
+   - **How users can get started**: Installation/setup instructions with usage examples
+   - **Where users can get help**: Support resources and documentation links
+   - **Who maintains and contributes**: Maintainer information and contribution guidelines
+
+## Guidelines
+
+### Content and Structure
+
+- Focus only on information necessary for developers to get started using and contributing to the project
+- Use clear, concise language and keep it scannable with good headings
+- Include relevant code examples and usage snippets
+- Add badges for build status, version, license if appropriate
+- Keep content under 500 KiB (GitHub truncates beyond this)
+
+### Technical Requirements
+
+- Use GitHub Flavored Markdown
+- Use relative links (e.g., `docs/CONTRIBUTING.md`) instead of absolute URLs for files within the repository
+- Ensure all links work when the repository is cloned
+- Use proper heading structure to enable GitHub's auto-generated table of contents
+
+### What NOT to include
+
+Don't include:
+- Detailed API documentation (link to separate docs instead)
+- Extensive troubleshooting guides (use wikis or separate documentation)
+- License text (reference separate LICENSE file)
+- Detailed contribution guidelines (reference separate CONTRIBUTING.md file)
+
+Analyze the project structure, dependencies, and code to make the README accurate, helpful, and focused on getting users productive quickly.
+```
+
+## How to use this prompt file
+
+1. Save the above content as `create-readme.prompt.md` in your `.github/prompts` folder of your repository.
+1. In {% data variables.product.prodname_vscode %}, display the {% data variables.copilot.copilot_chat_short %} view and enter `/create-readme`.
+
+{% data reusables.copilot.prompt-files-further-reading %}

content/copilot/tutorials/customization-library/prompt-files/document-api.md

@@ -0,0 +1,83 @@
+---
+title: Document API
+intro: 'Generate comprehensive API documentation from your code.'
+versions:
+  feature: copilot
+category:
+  - Prompt files
+  - Development workflows
+complexity:
+  - Advanced
+octicon: copilot
+topics:
+  - Copilot
+contentType: tutorials
+---
+
+{% data reusables.copilot.prompt-files-preview-note %}
+
+This prompt file generates OpenAPI 3.0 specifications for REST API endpoints by analyzing your API code and creating standardized, machine-readable documentation.
+
+## OpenAPI specification prompt
+
+```text copy
+---
+mode: 'agent'
+description: 'Generate OpenAPI 3.0 specification for API endpoints'
+---
+
+## Task
+
+Analyze the API endpoint code and generate a valid OpenAPI 3.0 specification in YAML format.
+
+## OpenAPI Structure
+
+Generate a complete OpenAPI spec including:
+
+1. **OpenAPI Header**
+   - OpenAPI version (3.0.3)
+   - API info (title, description, version)
+   - Server configuration
+
+2. **Path Definitions**
+   - HTTP method and path
+   - Operation summary and description
+   - Tags for organization
+
+3. **Parameters Schema**
+   - Path parameters with type validation
+   - Query parameters with constraints and defaults
+   - Request body schema using proper JSON Schema
+   - Required vs optional parameters
+
+4. **Response Schemas**
+   - Success responses (200, 201, etc.) with schema definitions
+   - Error responses (400, 401, 404, 500) with error schema
+   - Content-Type specifications
+   - Realistic example values
+
+5. **Components Section**
+   - Reusable schemas for request/response models
+   - Security schemes (Bearer token, API key, etc.)
+   - Common parameter definitions
+
+## Requirements
+
+- Generate valid OpenAPI 3.0.3 YAML that passes validation
+- Use proper JSON Schema for all data models
+- Include realistic example values, not placeholders
+- Define reusable components to avoid duplication
+- Add appropriate data validation (required fields, formats, constraints)
+- Include security requirements where applicable
+
+Focus on: ${input:endpoint_focus:Which specific endpoint or endpoints should be documented?}
+
+Generate production-ready OpenAPI specification that can be used with Swagger UI, Postman, and code generators.
+```
+
+## How to use this prompt file
+
+1. Save the above content as `document-api.prompt.md` in your `.github/prompts` folder.
+1. In {% data variables.product.prodname_vscode %}, display the {% data variables.copilot.copilot_chat_short %} view and enter `/document-api`. Optionally, you can also specify what specific endpoint you want documentation for by typing `endpoint_focus=GET /activities`, for example.
+
+{% data reusables.copilot.prompt-files-further-reading %}

content/copilot/tutorials/customization-library/prompt-files/generate-unit-tests.md

@@ -0,0 +1,84 @@
+---
+title: Generate unit tests
+intro: 'Create focused unit tests for your code.'
+versions:
+  feature: copilot
+category:
+  - Prompt files
+  - Development workflows
+complexity:
+  - Intermediate
+octicon: copilot
+topics:
+  - Copilot
+contentType: tutorials
+---
+
+{% data reusables.copilot.prompt-files-preview-note %}
+
+This prompt file generates focused unit tests for specific functions or methods, emphasizing practical test cases and maintainable code.
+
+## Unit test generation prompt
+
+```text copy
+---
+mode: 'agent'
+description: 'Generate unit tests for selected functions or methods'
+---
+
+## Task
+
+Analyze the selected function/method and generate focused unit tests that thoroughly validate its behavior.
+
+## Test Generation Strategy
+
+1. **Core Functionality Tests**
+   - Test the main purpose/expected behavior
+   - Verify return values with typical inputs
+   - Test with realistic data scenarios
+
+2. **Input Validation Tests**
+   - Test with invalid input types
+   - Test with null/undefined values
+   - Test with empty strings/arrays/objects
+   - Test boundary values (min/max, zero, negative numbers)
+
+3. **Error Handling Tests**
+   - Test expected exceptions are thrown
+   - Verify error messages are meaningful
+   - Test graceful handling of edge cases
+
+4. **Side Effects Tests** (if applicable)
+   - Verify external calls are made correctly
+   - Test state changes
+   - Validate interactions with dependencies
+
+## Test Structure Requirements
+
+- Use existing project testing framework and patterns
+- Follow AAA pattern: Arrange, Act, Assert
+- Write descriptive test names that explain the scenario
+- Group related tests in describe/context blocks
+- Mock external dependencies cleanly
+
+Target function: ${input:function_name:Which function or method should be tested?}
+Testing framework: ${input:framework:Which framework? (jest/vitest/mocha/pytest/rspec/etc)}
+
+## Guidelines
+
+- Generate 5-8 focused test cases covering the most important scenarios
+- Include realistic test data, not just simple examples
+- Add comments for complex test setup or assertions
+- Ensure tests are independent and can run in any order
+- Focus on testing behavior, not implementation details
+
+Create tests that give confidence the function works correctly and help catch regressions.
+```
+
+## How to use this prompt file
+
+1. Save the above content as `generate-unit-tests.prompt.md` in your `.github/prompts` folder.
+1. Open the code file containing the function(s) you want tests for. Optionally, you can highlight a specific function.
+1. In {% data variables.product.prodname_vscode %}, display the {% data variables.copilot.copilot_chat_short %} view and enter `/generate-unit-tests`. Optionally, you can also specify the target function and testing framework by typing `function_name=fetchActivities` and `framework=pytest`, for example.
+
+{% data reusables.copilot.prompt-files-further-reading %}

content/copilot/tutorials/customization-library/prompt-files/index.md

@@ -0,0 +1,18 @@
+---
+title: Prompt files
+intro: 'Reusable prompt examples for common development tasks.'
+versions:
+  feature: copilot
+topics:
+  - Copilot
+children:
+  - /your-first-prompt-file
+  - /create-readme
+  - /onboarding-plan
+  - /document-api
+  - /review-code
+  - /generate-unit-tests
+contentType: tutorials
+---
+
+{% data reusables.copilot.prompt-files-preview-note %}

content/copilot/tutorials/customization-library/prompt-files/onboarding-plan.md

@@ -0,0 +1,55 @@
+---
+title: Onboarding plan
+intro: 'A prompt file for getting personalized help with team onboarding.'
+versions:
+  feature: copilot
+category:
+  - Prompt files
+  - Team collaboration
+complexity:
+  - Simple
+octicon: copilot
+topics:
+  - Copilot
+contentType: tutorials
+---
+
+{% data reusables.copilot.prompt-files-preview-note %}
+
+## Onboarding plan prompt
+
+```text copy
+---
+mode: 'agent'
+description: 'Help new team members onboard with a phased plan and suggestions for first tasks.'
+---
+
+# Create My Onboarding Plan
+
+I'm a new team member joining ${input:team:Team or project name} and I need help creating a structured onboarding plan.
+
+My background: ${input:background:Briefly describe your experience level - new to tech, experienced developer new to this stack, etc.}
+
+Please create a personalized phased onboarding plan that includes the following phases.
+
+## Phase 1 - Foundation
+
+Environment setup with step-by-step instructions and troubleshooting tips, plus identifying the most important documentation to read first
+
+## Phase 2 - Exploration
+
+Codebase discovery starting with README files, running existing tests/scripts to understand workflows, and finding beginner-friendly first tasks like documentation improvements. If possible, find me specific open issues or tasks that are suitable for my background.
+
+## Phase 3 - Integration
+
+Learning team processes, making first contributions, and building confidence through early wins
+
+For each phase, break down complex topics into manageable steps, recommend relevant resources, provide concrete next steps, and suggest hands-on practice over just reading theory.
+```
+
+## How to use this prompt file
+
+1. Save the above content as `onboarding-plan.prompt.md` in your `.github/prompts` folder.
+1. In {% data variables.product.prodname_vscode %}, display the {% data variables.copilot.copilot_chat_short %} view and enter `/onboarding-plan`. Optionally, you can also specify your experience level by typing `background=experienced developer but new to stack`, for example.
+
+{% data reusables.copilot.prompt-files-further-reading %}

content/copilot/tutorials/customization-library/prompt-files/review-code.md

@@ -0,0 +1,93 @@
+---
+title: Review code
+intro: 'Perform comprehensive code reviews with structured feedback.'
+versions:
+  feature: copilot
+category:
+  - Prompt files
+  - Development workflows
+complexity:
+  - Advanced
+octicon: copilot
+topics:
+  - Copilot
+contentType: tutorials
+---
+
+{% data reusables.copilot.prompt-files-preview-note %}
+
+This prompt file conducts thorough code reviews and provides structured, actionable feedback as a single comprehensive report in {% data variables.copilot.copilot_chat_short %}.
+
+You can also use {% data variables.copilot.copilot_code-review_short %} in {% data variables.product.prodname_vscode %}, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review?tool=vscode). {% data variables.copilot.copilot_code-review_short %} gives interactive, step-by-step feedback with inline editor comments you can apply directly, while this prompt file gives a comprehensive report with educational explanations.
+
+## Code review prompt
+
+```text copy
+---
+mode: 'agent'
+description: 'Perform a comprehensive code review'
+---
+
+## Role
+
+You're a senior software engineer conducting a thorough code review. Provide constructive, actionable feedback.
+
+## Review Areas
+
+Analyze the selected code for:
+
+1. **Security Issues**
+   - Input validation and sanitization
+   - Authentication and authorization
+   - Data exposure risks
+   - Injection vulnerabilities
+
+2. **Performance & Efficiency**
+   - Algorithm complexity
+   - Memory usage patterns
+   - Database query optimization
+   - Unnecessary computations
+
+3. **Code Quality**
+   - Readability and maintainability
+   - Proper naming conventions
+   - Function/class size and responsibility
+   - Code duplication
+
+4. **Architecture & Design**
+   - Design pattern usage
+   - Separation of concerns
+   - Dependency management
+   - Error handling strategy
+
+5. **Testing & Documentation**
+   - Test coverage and quality
+   - Documentation completeness
+   - Comment clarity and necessity
+
+## Output Format
+
+Provide feedback as:
+
+**🔴 Critical Issues** - Must fix before merge
+**🟡 Suggestions** - Improvements to consider  
+**✅ Good Practices** - What's done well
+
+For each issue:
+- Specific line references
+- Clear explanation of the problem
+- Suggested solution with code example
+- Rationale for the change
+
+Focus on: ${input:focus:Any specific areas to emphasize in the review?}
+
+Be constructive and educational in your feedback.
+```
+
+## How to use this prompt file
+
+1. Save the above content as `review-code.prompt.md` in your `.github/prompts` folder.
+1. Open the code file you want to review in the editor.
+1. In {% data variables.product.prodname_vscode %}, display the {% data variables.copilot.copilot_chat_short %} view and enter `/review-code` to trigger the custom review using this prompt file. Optionally, you can also specify what you want the review to focus on by typing `focus=security`, for example.
+
+{% data reusables.copilot.prompt-files-further-reading %}

content/copilot/tutorials/customization-library/prompt-files/your-first-prompt-file.md

@@ -0,0 +1,67 @@
+---
+title: Your first prompt file
+intro: 'Create your first {% data variables.product.prodname_copilot_short %} prompt file with this simple code explanation example that works for any programming language.'
+versions:
+  feature: copilot
+category:
+  - Prompt files
+  - Getting started
+complexity:
+  - Simple
+octicon: copilot
+topics:
+  - Copilot
+contentType: tutorials
+---
+
+{% data reusables.copilot.prompt-files-preview-note %}
+
+## About customizations
+
+You can customize {% data variables.product.prodname_copilot %}'s responses using two types of files:
+
+* **Custom instructions** provide ongoing guidance for how {% data variables.product.prodname_copilot %} should behave across all your interactions. For an introductory example, see [AUTOTITLE](/copilot/tutorials/customization-library/custom-instructions/your-first-custom-instructions).
+* **Prompt files (public preview)** define reusable prompts for specific tasks that you can invoke when needed. Prompt files are only available in {% data variables.product.prodname_vscode_shortname %}.
+
+## Your first prompt file
+
+Start with this simple prompt file that helps you write clear, well-documented code explanations.
+
+### Code explanation prompt
+
+```text copy
+---
+mode: 'agent'
+description: 'Generate a clear code explanation with examples'
+---
+
+Explain the following code in a clear, beginner-friendly way:
+
+Code to explain: ${input:code:Paste your code here}
+Target audience: ${input:audience:Who is this explanation for? (e.g., beginners, intermediate developers, etc.)}
+
+Please provide:
+
+* A brief overview of what the code does
+* A step-by-step breakdown of the main parts
+* Explanation of any key concepts or terminology
+* A simple example showing how it works
+* Common use cases or when you might use this approach
+
+Use clear, simple language and avoid unnecessary jargon.
+```
+
+## Test it out
+
+1. Save the prompt file above as `explain-code.prompt.md` in your `.github/prompts` folder.
+1. In {% data variables.product.prodname_vscode %}, display the {% data variables.copilot.copilot_chat_short %} view and enter `/explain-code`.
+
+   {% data variables.product.prodname_copilot_short %} will switch to agent mode, if this is not already selected, and will prompt you to enter some code and an audience type.
+
+1. Enter:
+
+   ```text copy
+   The code is `function fibonacci(n) { return n <= 1 ? n : fibonacci(n-1) + fibonacci(n-2); }`. The audience is beginners.
+   ```
+
+{% data reusables.copilot.prompt-files-further-reading %}

content/copilot/tutorials/index.md

@@ -8,6 +8,7 @@ topics:
   - Copilot
 children:
   - /copilot-chat-cookbook
+  - /customization-library
   - /coding-agent
   - /compare-ai-models
   - /enhance-agent-mode-with-mcp

data/reusables/copilot/custom-instructions-further-reading.md

@@ -0,0 +1,5 @@
+## Further reading
+
+* [AUTOTITLE](/copilot/concepts/response-customization) - Overview of response customization in GitHub Copilot
+* [AUTOTITLE](/copilot/how-tos/configure-custom-instructions) - How to configure custom instructions
+* [Awesome GitHub Copilot Customizations](https://github.com/github/awesome-copilot/blob/main/README.instructions.md) - Repository of community-contributed custom instructions and other customizations for specific languages and scenarios

data/reusables/copilot/customization-examples-note.md

@@ -0,0 +1,4 @@
+> [!NOTE]
+> * The examples in this library are intended for inspiration—you are encouraged to adjust them to be more specific to your projects, languages, and team processes.
+> * For community-contributed examples of custom instructions for specific languages and scenarios, see the [Awesome GitHub Copilot Customizations](https://github.com/github/awesome-copilot/blob/main/README.instructions.md) repository.
+> * You can apply custom instructions across different scopes, depending on the platform or IDE where you are creating them. For more information, see "[AUTOTITLE](/copilot/concepts/response-customization)."

data/reusables/copilot/prompt-files-further-reading.md

@@ -0,0 +1,5 @@
+## Further reading
+
+* [Use prompt files in {% data variables.product.prodname_vscode %}](https://code.visualstudio.com/docs/copilot/customization/prompt-files) in the {% data variables.product.prodname_vscode %} documentation - Information on how to create and use prompt files
+* [AUTOTITLE](/copilot/concepts/response-customization) - Overview of response customization in GitHub Copilot
+* [Awesome GitHub Copilot Customizations](https://github.com/github/awesome-copilot/blob/main/README.prompts.md) - Repository of community-contributed custom prompt files and other customizations for specific languages and scenarios

data/reusables/copilot/prompt-files-preview-note.md

@@ -0,0 +1,3 @@
+> [!NOTE]
+> * {% data variables.product.prodname_copilot_short %} prompt files are in {% data variables.release-phases.public_preview %} and subject to change. Prompt files are only available in {% data variables.product.prodname_vscode_shortname %}. See [AUTOTITLE](/copilot/concepts/response-customization?tool=vscode#about-prompt-files).
+> * For community-contributed examples of prompt files for specific languages and scenarios, see the [Awesome GitHub Copilot Customizations](https://github.com/github/awesome-copilot/blob/main/README.prompts.md) repository.

data/reusables/copilot/repository-custom-instructions-types.md

@@ -0,0 +1,4 @@
+You can create repository custom instructions in two ways:
+
+* **Repository-wide instructions**: Create a single `copilot-instructions.md` file at the repository root that applies to all files in the repository.
+* **Path-specific instructions**: Create one or more `.instructions.md` files with an `applyTo` field that apply only to specific files or directories. Path-specific instructions are currently supported for **{% data variables.copilot.copilot_chat_short %}** in {% data variables.product.prodname_vscode %} and **{% data variables.product.prodname_copilot %} coding agent**.

data/ui.yml

@@ -339,9 +339,9 @@ alerts:
 
 cookbook_landing:
   spotlight: Spotlight
-  explore_articles: Explore {{ number }} prompt articles
+  explore_articles: Explore {{ number }} examples
   reset_filters: Reset filters
-  search_articles: Search articles
+  search_articles: Search examples
   category: Category
   complexity: Complexity
 

src/fixtures/fixtures/data/ui.yml

@@ -339,9 +339,9 @@ alerts:
 
 cookbook_landing:
   spotlight: Spotlight
-  explore_articles: Explore {{ number }} prompt articles
+  explore_articles: Explore {{ number }} examples
   reset_filters: Reset filters
-  search_articles: Search articles
+  search_articles: Search examples
   category: Category
   complexity: Complexity