Initial commit
This commit is contained in:
Zhongwei Li
210
skills/agent-documentation/SKILL.md
Normal file
210
skills/agent-documentation/SKILL.md
Normal file
@@ -0,0 +1,210 @@
|
||||
---
|
||||
name: agent-documentation
|
||||
description: Standards for creating AGENTS.md files that guide AI coding agents working with your codebase. Use when creating instructions for AI agents to follow project conventions, setup, and workflows.
|
||||
---
|
||||
|
||||
# AGENTS.md Documentation
|
||||
|
||||
This skill provides standards for creating AGENTS.md files - dedicated instructions for AI coding agents working with your codebase.
|
||||
|
||||
## What is AGENTS.md?
|
||||
|
||||
AGENTS.md is the "README for AI agents" - a machine-readable guide that provides explicit instructions for AI coding tools (like Claude, Copilot, Cursor) working with your project. Unlike README.md (for humans), AGENTS.md gives AI agents unambiguous, step-by-step guidance.
|
||||
|
||||
## Purpose
|
||||
|
||||
- **Centralized Instructions**: Single source of truth for all AI agents
|
||||
- **Explicit Guidance**: Clear setup commands, coding standards, testing workflows
|
||||
- **Project Context**: Architecture decisions, conventions, constraints
|
||||
- **Consistency**: Ensures AI-generated code matches project standards
|
||||
|
||||
## AGENTS.md Structure
|
||||
|
||||
Based on real-world examples, a well-structured AGENTS.md follows this pattern:
|
||||
|
||||
```markdown
|
||||
# ProjectName - Development Guide
|
||||
|
||||
**Stack**: [Tech stack components]
|
||||
**Principles**: [Core development principles, e.g., SOLID, KISS, YAGNI]
|
||||
|
||||
## Project Overview
|
||||
|
||||
[Brief description of architecture and approach]
|
||||
|
||||
## Repository Structure
|
||||
|
||||
- `path/to/main/`: [Description]
|
||||
- `path/to/tests/`: [Description]
|
||||
- `path/to/config/`: [Description]
|
||||
|
||||
## Key Commands
|
||||
|
||||
```bash
|
||||
# Core commands
|
||||
[build command]
|
||||
[test command]
|
||||
[format command]
|
||||
|
||||
# Additional tools
|
||||
[migration/deployment commands]
|
||||
[additional commands]
|
||||
```
|
||||
|
||||
## Quality Gates (Required)
|
||||
|
||||
Define the quality standards that must be met:
|
||||
|
||||
### Code Quality
|
||||
- [ ] Build succeeds without errors
|
||||
- [ ] All tests pass
|
||||
- [ ] Code formatting/linting passes
|
||||
- [ ] No compiler warnings
|
||||
|
||||
### Testing Requirements
|
||||
- [ ] Integration tests for key workflows (favor sociable tests over isolated unit tests)
|
||||
- [ ] Avoid excessive mocking - test real collaborations
|
||||
- [ ] All edge cases and error paths covered
|
||||
|
||||
### Code Review Standards
|
||||
- [ ] Follows project conventions
|
||||
- [ ] No code smells or anti-patterns
|
||||
- [ ] Proper error handling
|
||||
- [ ] Security considerations addressed
|
||||
|
||||
## Coding Conventions (Optional)
|
||||
|
||||
[Project-specific coding standards]
|
||||
|
||||
## Testing Guidelines (Optional)
|
||||
|
||||
[Testing expectations]
|
||||
|
||||
```
|
||||
|
||||
## Key Sections Explained
|
||||
|
||||
### 1. Title and Metadata (Required)
|
||||
**Format**: `# ProjectName - Development Guide`
|
||||
|
||||
Include **Stack** and **Principles** at the top for quick reference.
|
||||
|
||||
### 2. Project Overview (Required)
|
||||
Brief architectural summary - what type of project, key technologies, approach.
|
||||
|
||||
### 3. Repository Structure (Required)
|
||||
Map of directories with brief descriptions. Helps agents understand where code lives.
|
||||
|
||||
### 4. Key Commands (Required)
|
||||
Copy-paste commands for:
|
||||
- Building the project
|
||||
- Running tests
|
||||
- Formatting code
|
||||
- Database migrations or other critical operations
|
||||
|
||||
### 5. Quality Gates (Required)
|
||||
Define quality standards that code must meet:
|
||||
- **Code Quality**: Build, test, lint requirements
|
||||
- **Testing Requirements**: Coverage thresholds, test types needed
|
||||
- **Code Review Standards**: Conventions, patterns, security checks
|
||||
|
||||
### 6. Optional Sections
|
||||
Add as needed:
|
||||
- **Coding Conventions**: Project-specific rules
|
||||
- **Testing Guidelines**: Reference separate tests/AGENTS.md for detailed testing guidelines
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Start with Essentials
|
||||
Include at minimum: Stack, Principles, Project Overview, Repository Structure, and Key Commands.
|
||||
|
||||
### Be Explicit and Specific
|
||||
❌ "Set up the environment"
|
||||
✅ "npm install && cp .env.example .env"
|
||||
|
||||
❌ "Write good tests"
|
||||
✅ "Write integration tests for all API endpoints, test real collaborations"
|
||||
|
||||
### Use Exact Commands
|
||||
Provide copy-paste ready commands. AI agents will execute them literally.
|
||||
|
||||
### Keep It Updated
|
||||
Review and update AGENTS.md when project structure or conventions change.
|
||||
|
||||
## Integration with Claude Code
|
||||
|
||||
AGENTS.md works alongside Claude Code agents:
|
||||
- Claude Code agents can reference AGENTS.md for project context
|
||||
- Use AGENTS.md for project-specific conventions
|
||||
- Use agent specifications (.md files) for agent-specific behavior
|
||||
|
||||
## Complete Example
|
||||
|
||||
```markdown
|
||||
# StockToolset - Development Guide
|
||||
|
||||
**Stack**: .NET 10, ASP.NET Core Minimal APIs, .NET Aspire 13, PostgreSQL, PGMQ.
|
||||
**Principles**: SOLID, KISS, YAGNI. Consistency over innovation.
|
||||
|
||||
## Project Overview
|
||||
|
||||
Cloud-native .NET 10 modular monolith using Vertical Slice Architecture,
|
||||
Aspire 13, PostgreSQL, and PGMQ.
|
||||
|
||||
## Repository Structure
|
||||
|
||||
- `StockStorage/src/`: Main app (Features/, Database/, Infrastructure/)
|
||||
- `StockStorage/tests/`: Unified test project (Unit, Integration, System). **See `StockStorage/tests/AGENTS.md`**.
|
||||
- `StockStorage.AppHost/`: .NET Aspire orchestration
|
||||
- `StockStorage.ServiceDefaults/`: Shared Aspire defaults
|
||||
|
||||
## Key Commands
|
||||
|
||||
```bash
|
||||
# Core
|
||||
dotnet build
|
||||
dotnet test # Requires Docker
|
||||
dotnet format
|
||||
|
||||
# EF Core
|
||||
dotnet ef migrations add <MigrationName>
|
||||
dotnet ef database update
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
**Refer to `StockStorage/tests/AGENTS.md` for all testing guidelines.**
|
||||
|
||||
- Stack: TUnit, AwesomeAssertions, Testcontainers.
|
||||
- Categories: Unit, Integration, System.
|
||||
|
||||
## Quality Gates
|
||||
|
||||
### Code Quality
|
||||
- [ ] `dotnet build` succeeds with zero warnings
|
||||
- [ ] `dotnet format` shows no formatting issues
|
||||
- [ ] All tests pass (`dotnet test`)
|
||||
|
||||
### Testing Requirements
|
||||
- [ ] Integration tests for key workflows (favor sociable tests)
|
||||
- [ ] Avoid excessive mocking - test real collaborations
|
||||
- [ ] All edge cases and error paths tested
|
||||
|
||||
### Code Review Standards
|
||||
- [ ] Follows Vertical Slice Architecture
|
||||
- [ ] SOLID, KISS, YAGNI principles applied
|
||||
- [ ] No code duplication
|
||||
- [ ] Proper error handling and logging
|
||||
|
||||
## Coding Conventions
|
||||
|
||||
- Follow SOLID, KISS, YAGNI principles
|
||||
- Consistency over innovation
|
||||
- Use Vertical Slice Architecture per feature
|
||||
```
|
||||
|
||||
## Further Reading
|
||||
|
||||
- [AGENTS.md Specification](https://agents.md/)
|
||||
- [GitHub's AGENTS.md Guide](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/)
|
||||
- [OpenAI AGENTS.md Repo](https://github.com/openai/agents.md)
|
||||
Reference in New Issue
Block a user