{"kind":"AgentDefinition","metadata":{"namespace":"community","name":"instructions","version":"0.1.0"},"spec":{"agents_md":"---\ndescription: 'Guidelines for creating high-quality custom instruction files for GitHub Copilot'\napplyTo: '**/*.instructions.md'\n---\n\n# Custom Instructions File Guidelines\n\nInstructions for creating effective and maintainable custom instruction files that guide GitHub Copilot in generating domain-specific code and following project conventions.\n\n## Project Context\n\n- Target audience: Developers and GitHub Copilot working with domain-specific code\n- File format: Markdown with YAML frontmatter\n- File naming convention: lowercase with hyphens (e.g., `react-best-practices.instructions.md`)\n- Location: `.github/instructions/` directory\n- Purpose: Provide context-aware guidance for code generation, review, and documentation\n\n## Required Frontmatter\n\nEvery instruction file must include YAML frontmatter with the following fields:\n\n```yaml\n---\ndescription: 'Brief description of the instruction purpose and scope'\napplyTo: 'glob pattern for target files (e.g., **/*.ts, **/*.py)'\n---\n```\n\n### Frontmatter Guidelines\n\n- **description**: Single-quoted string, 1-500 characters, clearly stating the purpose\n- **applyTo**: Glob pattern(s) specifying which files these instructions apply to\n  - Single pattern: `'**/*.ts'`\n  - Multiple patterns: `'**/*.ts, **/*.tsx, **/*.js'`\n  - Specific files: `'src/**/*.py'`\n  - All files: `'**'`\n\n## File Structure\n\nA well-structured instruction file should include the following sections:\n\n### 1. Title and Overview\n\n- Clear, descriptive title using `#` heading\n- Brief introduction explaining the purpose and scope\n- Optional: Project context section with key technologies and versions\n\n### 2. Core Sections\n\nOrganize content into logical sections based on the domain:\n\n- **General Instructions**: High-level guidelines and principles\n- **Best Practices**: Recommended patterns and approaches\n- **Code Standards**: Naming conventions, formatting, style rules\n- **Architecture/Structure**: Project organization and design patterns\n- **Common Patterns**: Frequently used implementations\n- **Security**: Security considerations (if applicable)\n- **Performance**: Optimization guidelines (if applicable)\n- **Testing**: Testing standards and approaches (if applicable)\n\n### 3. Examples and Code Snippets\n\nProvide concrete examples with clear labels:\n\n```markdown\n### Good Example\n\\`\\`\\`language\n// Recommended approach\ncode example here\n\\`\\`\\`\n\n### Bad Example\n\\`\\`\\`language\n// Avoid this pattern\ncode example here\n\\`\\`\\`\n```\n\n### 4. Validation and Verification (Optional but Recommended)\n\n- Build commands to verify code\n- Linting and formatting tools\n- Testing requirements\n- Verification steps\n\n## Content Guidelines\n\n### Writing Style\n\n- Use clear, concise language\n- Write in imperative mood (\"Use\", \"Implement\", \"Avoid\")\n- Be specific and actionable\n- Avoid ambiguous terms like \"should\", \"might\", \"possibly\"\n- Use bullet points and lists for readability\n- Keep sections focused and scannable\n\n### Best Practices\n\n- **Be Specific**: Provide concrete examples rather than abstract concepts\n- **Show Why**: Explain the reasoning behind recommendations when it adds value\n- **Use Tables**: For comparing options, listing rules, or showing patterns\n- **Include Examples**: Real code snippets are more effective than descriptions\n- **Stay Current**: Reference current versions and best practices\n- **Link Resources**: Include official documentation and authoritative sources\n\n### Instruction Altitude (Goldilocks Zone)\n\n- Start with the minimum rule set that fully defines expected outcomes\n- Add constraints after observed failures, not hypothetical edge cases\n- Prefer high-signal examples over exhaustive decision tables\n\n| Altitude | Failure Mode | Result |\n| --- | --- | --- |\n| Over-specified | Brittle if-else prose | Breaks on unlisted cases |\n| Under-specified | Assumes shared context | Generic outputs |\n| Right altitude | Heuristics + examples | Stable, generalizable quality |\n\n### Common Patterns to Include\n\n1. **Naming Conventions**: How to name variables, functions, classes, files\n2. **Code Organization**: File structure, module organization, import order\n3. **Error Handling**: Preferred error handling patterns\n4. **Dependencies**: How to manage and document dependencies\n5. **Comments and Documentation**: When and how to document code\n6. **Version Information**: Target language/framework versions\n\n## Patterns to Follow\n\n### Bullet Points and Lists\n\n```markdown\n## Security Best Practices\n\n- Always validate user input before processing\n- Use parameterized queries to prevent SQL injection\n- Store secrets in environment variables, never in code\n- Implement proper authentication and authorization\n- Enable HTTPS for all production endpoints\n```\n\n### Tables for Structured Information\n\n```markdown\n## Common Issues\n\n| Issue            | Solution            | Example                       |\n| ---------------- | ------------------- | ----------------------------- |\n| Magic numbers    | Use named constants | `const MAX_RETRIES = 3`       |\n| Deep nesting     | Extract functions   | Refactor nested if statements |\n| Hardcoded values | Use configuration   | Store API URLs in config      |\n```\n\n### Code Comparison\n\n```markdown\n### Good Example - Using TypeScript interfaces\n\\`\\`\\`typescript\ninterface User {\n  id: string;\n  name: string;\n  email: string;\n}\n\nfunction getUser(id: string): User {\n  // Implementation\n}\n\\`\\`\\`\n\n### Bad Example - Using any type\n\\`\\`\\`typescript\nfunction getUser(id: any): any {\n  // Loses type safety\n}\n\\`\\`\\`\n```\n\n### Conditional Guidance\n\n```markdown\n## Framework Selection\n\n- **For small projects**: Use Minimal API approach\n- **For large projects**: Use controller-based architecture with clear separation\n- **For microservices**: Consider domain-driven design patterns\n```\n\n## Patterns to Avoid\n\n- **Overly verbose explanations**: Keep it concise and scannable\n- **Outdated information**: Always reference current versions and practices\n- **Ambiguous guidelines**: Be specific about what to do or avoid\n- **Missing examples**: Abstract rules without concrete code examples\n- **Contradictory advice**: Ensure consistency throughout the file\n- **Copy-paste from documentation**: Add value by distilling and contextualizing\n- **Hypothetical-rule inflation**: Do not add rules for failures that have not occurred\n\n## Testing Your Instructions\n\nBefore finalizing instruction files:\n\n1. **Test with Copilot**: Try the instructions with actual prompts in VS Code\n2. **Verify Examples**: Ensure code examples are correct and run without errors\n3. **Check Glob Patterns**: Confirm `applyTo` patterns match intended files\n\n## Example Structure\n\nHere's a minimal example structure for a new instruction file:\n\n```markdown\n---\ndescription: 'Brief description of purpose'\napplyTo: '**/*.ext'\n---\n\n# Technology Name Development\n\nBrief introduction and context.\n\n## General Instructions\n\n- High-level guideline 1\n- High-level guideline 2\n\n## Best Practices\n\n- Specific practice 1\n- Specific practice 2\n\n## Code Standards\n\n### Naming Conventions\n- Rule 1\n- Rule 2\n\n### File Organization\n- Structure 1\n- Structure 2\n\n## Common Patterns\n\n### Pattern 1\nDescription and example\n\n\\`\\`\\`language\ncode example\n\\`\\`\\`\n\n### Pattern 2\nDescription and example\n\n## Validation\n\n- Build command: `command to verify`\n- Linting: `command to lint`\n- Testing: `command to test`\n```\n\n## Maintenance\n\n- Review instructions when dependencies or frameworks are updated\n- Update examples to reflect current best practices\n- Remove outdated patterns or deprecated features\n- Add new patterns as they emerge in the community\n- Keep glob patterns accurate as project structure evolves\n\n## Additional Resources\n\n- [Custom Instructions Documentation](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)\n- [Awesome Copilot Instructions](https://github.com/github/awesome-copilot/tree/main/instructions)\n- [System Prompt Altitude — Effective Context Engineering for AI Agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents#the-anatomy-of-effective-context)\n","description":"Guidelines for creating high-quality custom instruction files for GitHub Copilot","import":{"commit_sha":"541b7819d8c3545c6df122491af4fa1eae415779","imported_at":"2026-05-18T20:05:35Z","license_text":"MIT License\n\nCopyright GitHub, Inc.\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.","owner":"github","repo":"github/awesome-copilot","source_url":"https://github.com/github/awesome-copilot/blob/541b7819d8c3545c6df122491af4fa1eae415779/instructions/instructions.instructions.md"},"manifest":{}},"content_hash":[67,134,48,184,171,199,1,250,110,36,177,229,86,207,238,233,64,214,68,223,86,183,186,144,197,123,118,174,17,36,65,144],"trust_level":"unsigned","yanked":false}