Skip to content

Commit 576d486

Browse files
AClerboisAClerbois
authored
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
1 parent 14285a2 commit 576d486

File tree

2 files changed

+166
-0
lines changed

2 files changed

+166
-0
lines changed

‎AGENTS.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# AGENTS.md
2+
3+
## Project Overview
4+
5+
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:
6+
7+
- **Agents** - Specialized GitHub Copilot agents that integrate with MCP servers
8+
- **Prompts** - Task-specific prompts for code generation and problem-solving
9+
- **Instructions** - Coding standards and best practices applied to specific file patterns
10+
- **Collections** - Curated collections organized around specific themes and workflows
11+
12+
## Repository Structure
13+
14+
```
15+
.
16+
├── agents/ # Custom GitHub Copilot agent definitions (.agent.md files)
17+
├── prompts/ # Task-specific prompts (.prompt.md files)
18+
├── instructions/ # Coding standards and guidelines (.instructions.md files)
19+
├── collections/ # Curated collections of resources (.md files)
20+
├── docs/ # Documentation for different resource types
21+
├── eng/ # Build and automation scripts
22+
└── scripts/ # Utility scripts
23+
```
24+
25+
## Setup Commands
26+
27+
```bash
28+
# Install dependencies
29+
npm ci
30+
31+
# Build the project (generates README.md)
32+
npm run build
33+
34+
# Validate collection manifests
35+
npm run collection:validate
36+
37+
# Create a new collection
38+
npm run collection:create -- --id <collection-id> --tags <tags>
39+
```
40+
41+
## Development Workflow
42+
43+
### Working with Agents, Prompts, and Instructions
44+
45+
All agent files (`*.agent.md`), prompt files (`*.prompt.md`), and instruction files (`*.instructions.md`) must include proper markdown front matter:
46+
47+
#### Agent Files (*.agent.md)
48+
- Must have `description` field (wrapped in single quotes)
49+
- File names should be lower case with words separated by hyphens
50+
- Recommended to include `tools` field
51+
- Strongly recommended to specify `model` field
52+
53+
#### Prompt Files (*.prompt.md)
54+
- Must have `agent` field (value should be `'agent'` wrapped in single quotes)
55+
- Must have `description` field (wrapped in single quotes, not empty)
56+
- File names should be lower case with words separated by hyphens
57+
- Recommended to specify `tools` if applicable
58+
- Strongly recommended to specify `model` field
59+
60+
#### Instruction Files (*.instructions.md)
61+
- Must have `description` field (wrapped in single quotes, not empty)
62+
- Must have `applyTo` field specifying file patterns (e.g., `'**.js, **.ts'`)
63+
- File names should be lower case with words separated by hyphens
64+
65+
### Adding New Resources
66+
67+
When adding a new agent, prompt, or instruction file:
68+
69+
1. Create the file with proper front matter
70+
2. Add the file to the appropriate directory
71+
3. Update the README.md by running: `npm run build`
72+
4. Verify the resource appears in the generated README
73+
74+
### Testing Instructions
75+
76+
```bash
77+
# Run all validation checks
78+
npm run collection:validate
79+
80+
# Build and verify README generation
81+
npm run build
82+
83+
# Fix line endings (required before committing)
84+
bash scripts/fix-line-endings.sh
85+
```
86+
87+
Before committing:
88+
- Ensure all markdown front matter is correctly formatted
89+
- Verify file names follow the lower-case-with-hyphens convention
90+
- Run `npm run build` to update the README
91+
- **Always run `bash scripts/fix-line-endings.sh`** to normalize line endings (CRLF → LF)
92+
- Check that your new resource appears correctly in the README
93+
94+
## Code Style Guidelines
95+
96+
### Markdown Files
97+
- Use proper front matter with required fields
98+
- Keep descriptions concise and informative
99+
- Wrap description field values in single quotes
100+
- Use lower-case file names with hyphens as separators
101+
102+
### JavaScript/Node.js Scripts
103+
- Located in `eng/` and `scripts/` directories
104+
- Follow Node.js ES module conventions (`.mjs` extension)
105+
- Use clear, descriptive function and variable names
106+
107+
## Pull Request Guidelines
108+
109+
When creating a pull request:
110+
111+
1. **README updates**: New files should automatically be added to the README when you run `npm run build`
112+
2. **Front matter validation**: Ensure all markdown files have the required front matter fields
113+
3. **File naming**: Verify all new files follow the lower-case-with-hyphens naming convention
114+
4. **Build check**: Run `npm run build` before committing to verify README generation
115+
5. **Line endings**: **Always run `bash scripts/fix-line-endings.sh`** to normalize line endings to LF (Unix-style)
116+
6. **Description**: Provide a clear description of what your agent/prompt/instruction does
117+
7. **Testing**: If adding a collection, run `npm run collection:validate` to ensure validity
118+
119+
### Pre-commit Checklist
120+
121+
Before submitting your PR, ensure you have:
122+
- [ ] Run `npm install` (or `npm ci`) to install dependencies
123+
- [ ] Run `npm run build` to generate the updated README.md
124+
- [ ] Run `bash scripts/fix-line-endings.sh` to normalize line endings
125+
- [ ] Verified that all new files have proper front matter
126+
- [ ] Tested that your contribution works with GitHub Copilot
127+
- [ ] Checked that file names follow the naming convention
128+
129+
### Code Review Checklist
130+
131+
For prompt files (*.prompt.md):
132+
- [ ] Has markdown front matter
133+
- [ ] Has `agent` field (value should be `'agent'` wrapped in single quotes)
134+
- [ ] Has non-empty `description` field wrapped in single quotes
135+
- [ ] File name is lower case with hyphens
136+
- [ ] Includes `model` field (strongly recommended)
137+
138+
For instruction files (*.instructions.md):
139+
- [ ] Has markdown front matter
140+
- [ ] Has non-empty `description` field wrapped in single quotes
141+
- [ ] Has `applyTo` field with file patterns
142+
- [ ] File name is lower case with hyphens
143+
144+
For agent files (*.agent.md):
145+
- [ ] Has markdown front matter
146+
- [ ] Has non-empty `description` field wrapped in single quotes
147+
- [ ] File name is lower case with hyphens
148+
- [ ] Includes `model` field (strongly recommended)
149+
- [ ] Considers using `tools` field
150+
151+
## Contributing
152+
153+
This is a community-driven project. Contributions are welcome! Please see:
154+
- [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines
155+
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards
156+
- [SECURITY.md](SECURITY.md) for security policies
157+
158+
## MCP Server
159+
160+
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.
161+
162+
## License
163+
164+
MIT License - see [LICENSE](LICENSE) for details

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,8 @@ We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.
8787
- Improve existing content
8888
- Report issues or suggest enhancements
8989

90+
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.
91+
9092
### Quick Contribution Guide
9193

9294
1. Follow our file naming conventions and frontmatter requirements

0 commit comments

Comments
 (0)