feat: Add AGENTS.md file with project guidance for AI coding agents

AGENTS.md

@@ -0,0 +1,164 @@
+# 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
+
+```bash
+# 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
+
+```bash
+# 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](CONTRIBUTING.md) for contribution guidelines
+- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards
+- [SECURITY.md](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](LICENSE) for details

README.md

@@ -87,6 +87,8 @@ We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.
 - Improve existing content
 - Report issues or suggest enhancements
 
+For AI coding agents working with this project, refer to [AGENTS.md](AGENTS.md) for detailed technical guidance on development workflows, setup commands, and contribution standards.
+
 ### Quick Contribution Guide
 
 1. Follow our file naming conventions and frontmatter requirements