diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..cd2961cc --- /dev/null +++ b/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 --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 diff --git a/README.md b/README.md index 282e7b5a..e6cdf1a0 100644 --- a/README.md +++ b/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