awesome-copilot/AGENTS.md

AGENTS.md

Project Overview

The Awesome GitHub Copilot repository is a community-driven collection of custom agents, prompts, and instructions designed to enhance GitHub Copilot experiences across various domains, languages, and use cases. The project includes:

• Agents - Specialized GitHub Copilot agents that integrate with MCP servers
• Prompts - Task-specific prompts for code generation and problem-solving
• Instructions - Coding standards and best practices applied to specific file patterns
• Collections - Curated collections organized around specific themes and workflows

Repository Structure

.
├── agents/           # Custom GitHub Copilot agent definitions (.agent.md files)
├── prompts/          # Task-specific prompts (.prompt.md files)
├── instructions/     # Coding standards and guidelines (.instructions.md files)
├── collections/      # Curated collections of resources (.md files)
├── docs/             # Documentation for different resource types
├── eng/              # Build and automation scripts
└── scripts/          # Utility scripts

Setup Commands

# Install dependencies
npm ci

# Build the project (generates README.md)
npm run build

# Validate collection manifests
npm run collection:validate

# Create a new collection
npm run collection:create -- --id <collection-id> --tags <tags>

Development Workflow

Working with Agents, Prompts, and Instructions

All agent files (*.agent.md), prompt files (*.prompt.md), and instruction files (*.instructions.md) must include proper markdown front matter:

Agent Files (*.agent.md)

• Must have description field (wrapped in single quotes)
• File names should be lower case with words separated by hyphens
• Recommended to include tools field
• Strongly recommended to specify model field

Prompt Files (*.prompt.md)

• Must have agent field (value should be 'agent' wrapped in single quotes)
• Must have description field (wrapped in single quotes, not empty)
• File names should be lower case with words separated by hyphens
• Recommended to specify tools if applicable
• Strongly recommended to specify model field

Instruction Files (*.instructions.md)

• Must have description field (wrapped in single quotes, not empty)
• Must have applyTo field specifying file patterns (e.g., '**.js, **.ts')
• File names should be lower case with words separated by hyphens

Adding New Resources

When adding a new agent, prompt, or instruction file:

1. Create the file with proper front matter
2. Add the file to the appropriate directory
3. Update the README.md by running: npm run build
4. Verify the resource appears in the generated README

Testing Instructions

# Run all validation checks
npm run collection:validate

# Build and verify README generation
npm run build

# Fix line endings (required before committing)
bash scripts/fix-line-endings.sh

Before committing:

• Ensure all markdown front matter is correctly formatted
• Verify file names follow the lower-case-with-hyphens convention
• Run npm run build to update the README
• Always run bash scripts/fix-line-endings.sh to normalize line endings (CRLF → LF)
• Check that your new resource appears correctly in the README

Code Style Guidelines

Markdown Files

• Use proper front matter with required fields
• Keep descriptions concise and informative
• Wrap description field values in single quotes
• Use lower-case file names with hyphens as separators

JavaScript/Node.js Scripts

• Located in eng/ and scripts/ directories
• Follow Node.js ES module conventions (.mjs extension)
• Use clear, descriptive function and variable names

Pull Request Guidelines

When creating a pull request:

1. README updates: New files should automatically be added to the README when you run npm run build
2. Front matter validation: Ensure all markdown files have the required front matter fields
3. File naming: Verify all new files follow the lower-case-with-hyphens naming convention
4. Build check: Run npm run build before committing to verify README generation
5. Line endings: Always run bash scripts/fix-line-endings.sh to normalize line endings to LF (Unix-style)
6. Description: Provide a clear description of what your agent/prompt/instruction does
7. Testing: If adding a collection, run npm run collection:validate to ensure validity

Pre-commit Checklist

Before submitting your PR, ensure you have:

• Run npm install (or npm ci) to install dependencies
• Run npm run build to generate the updated README.md
• Run bash scripts/fix-line-endings.sh to normalize line endings
• Verified that all new files have proper front matter
• Tested that your contribution works with GitHub Copilot
• Checked that file names follow the naming convention

Code Review Checklist

For prompt files (*.prompt.md):

• Has markdown front matter
• Has agent field (value should be 'agent' wrapped in single quotes)
• Has non-empty description field wrapped in single quotes
• File name is lower case with hyphens
• Includes model field (strongly recommended)

For instruction files (*.instructions.md):

• Has markdown front matter
• Has non-empty description field wrapped in single quotes
• Has applyTo field with file patterns
• File name is lower case with hyphens

For agent files (*.agent.md):

• Has markdown front matter
• Has non-empty description field wrapped in single quotes
• File name is lower case with hyphens
• Includes model field (strongly recommended)
• Considers using tools field

Contributing

This is a community-driven project. Contributions are welcome! Please see:

• CONTRIBUTING.md for contribution guidelines
• CODE_OF_CONDUCT.md for community standards
• SECURITY.md for security policies

MCP Server

The repository includes an MCP (Model Context Protocol) Server that provides prompts for searching and installing resources directly from this repository. Docker is required to run the server.

License

MIT License - see LICENSE for details