mirror of
https://github.com/github/awesome-copilot.git
synced 2026-02-20 02:15:12 +00:00
feat: Add AGENTS.md file with project guidance for AI coding agents (#477)
* feat: Add AGENTS.md file with project guidance for AI coding agents * docs: Update AGENTS.md with line endings script requirement * fix: Correct 'mode' field to 'agent' in prompt files documentation and add AGENTS.md reference to README
This commit is contained in:
Adrien Clerbois
GitHub
164
AGENTS.md
Normal file
164
AGENTS.md
Normal file
@@ -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
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user