"1.0.0" # Semantic versioning: MAJOR.MINOR.PATCH to "1.0.0" # Semantic versioning: MAJOR.MINOR.PATCH
20 added, 0 removed. Audit A to A.
---
# Required fields — fill in all of these
id: your-agent-name # Must match directory name. Lowercase, hyphens only. Never change after creation.
version: "1.0.0" # Semantic versioning: MAJOR.MINOR.PATCH
title: "Human-Readable Agent Title"
type: agent # This is agent instructions (not skill/prompt/workflow/lesson)
description: "One sentence describing this agent's purpose and when to use it"
# Status and ownership
status: experimental # experimental | recommended | deprecated (start with experimental)
owners:
- "@your-github-handle" # GitHub handle(s) responsible for this agent
# Audience
primary_personas:
- developers # Who uses this agent? developers | agents | security | all
- agents # Agent instructions typically target both developers and agents
# Dependencies
requires:
anchors: [] # Other patterns to load first (usually empty)
skills: [] # Skills this agent should use
# Output specification
output:
format: markdown # markdown | json | yaml | text
contract:
required_sections:
- "Core Principles" # Sections that must appear in agent output
- "Work Practices"
prohibited_content: # Content that must NEVER appear (minimum 4)
- "Secrets"
- "Real PII"
- "Real CUI"
- "Internal URLs"
# Quality requirements
quality_gates:
readability_max_grade: 10 # Maximum Flesch-Kincaid grade level (8 = general public, 10 = technical)
citations_required: false # true if making compliance/regulatory claims
# Recommended fields below (uncomment and fill in as needed)
# triggers: # Keywords that suggest using this agent
# - "keyword1"
# - "keyword2"
# tags: # Keywords for discovery and filtering
# - "tag1"
# - "tag2"
# portability: # Tool compatibility flags
# opencode: true # OpenCode supports AGENTS.md
# cursor: false # Cursor uses .cursorrules
# claude_projects: true # Claude Projects support agent instructions
# chatgpt: false # ChatGPT uses custom instructions
# generic_llm: true # Works with generic LLM interfaces
# scope:
# intended_use:
# - "What this agent is designed for"
# exclusions:
# - "What NOT to use this agent for"
# changelog: # Version history
# - version: "1.0.0"
# date: "2026-05-20"
# change_type: major
# summary: "Initial release"
---
# Agent: Your Agent Title
Brief description of what this agent does (2-3 sentences). Explain the agent's role, what problems it solves, and when someone would use it.
> **Note:** These are specialized agent instructions. For general repository rules, see [main AGENTS.md](../../AGENTS.md)
## Core Principles
Define the agent's core operating principles (priority hierarchy):
```
principle1 > principle2 > principle3 > principle4
```
1. **Principle 1** — Brief explanation
2. **Principle 2** — Brief explanation
3. **Principle 3** — Brief explanation
4. **Principle 4** — Brief explanation
## When to Use
- Scenario 1 when this agent is helpful
- Scenario 2 when you should use this agent
- User asks "help me with [specific task]"
- Working on [specific domain/problem]
## Work Practices
### 1. First Practice Area
**MUST:**
+
- Required behavior 1
- Required behavior 2
- Required behavior 3
**MUST NOT:**
+
- Prohibited behavior 1
- Prohibited behavior 2
**Example:**
+
```bash
# Good example
command --correct-option
```
```bash
# Bad example - avoid this
command --wrong-option
```
### 2. Second Practice Area
**SHOULD:**
+
- Recommended behavior 1
- Recommended behavior 2
**SHOULD NOT:**
+
- Discouraged behavior 1
- Discouraged behavior 2
**When:**
+
- Condition when this practice applies
### 3. Third Practice Area
Describe another important practice area for this agent.
**Steps:**
+
1. First step in this practice
2. Second step in this practice
3. Verification step
## Validation Requirements
Before completing tasks, the agent MUST verify:
### Code Changes
+
- [ ] First verification checkpoint
- [ ] Second verification checkpoint
- [ ] Third verification checkpoint
```bash
# Validation commands
make validate
make test
```
### Documentation Changes
+
- [ ] Documentation verification 1
- [ ] Documentation verification 2
## Safety Requirements
### Input Handling
The agent MUST:
+
- Define how to handle user input safely
- Validate input boundaries
- Sanitize sensitive data
### Output Standards
The agent MUST:
+
- Follow output contract in frontmatter
- Never include prohibited content
- Format output consistently
### Error Handling
The agent MUST:
+
- Handle errors gracefully
- Provide clear error messages
- Never expose sensitive information in errors
## Tool Usage
### Required Tools
+
- Tool 1 (with version if applicable)
- Tool 2 (with version if applicable)
### Recommended Tools
+
- Optional tool 1 — for what purpose
- Optional tool 2 — for what purpose
### Tool Safety
+
- How to use tools safely
- What to avoid with tools
- Verification commands
## Collaboration Patterns
When working with other agents or humans:
**MUST:**
+
- Clear handoff procedures
- Document assumptions
- Report blockers
**Pattern:**
+
1. Receive task
2. Clarify requirements
3. Execute work
4. Verify output
5. Hand off results
## Examples
### Example 1: Common Use Case
Describe a typical scenario where this agent would be used.
**Input:**
+
```
Example task description
```
**Agent Actions:**
+
1. First action the agent takes
2. Second action the agent takes
3. Verification action
**Output:**
+
```
Expected output format
```
### Example 2: Edge Case (if relevant)
Show how the agent handles a tricky situation.
## Troubleshooting
Common issues this agent might encounter and how to resolve them:
| Issue | Cause | Resolution |
|-------|-------|------------|
| Error condition 1 | Why it happens | How agent should respond |
| Error condition 2 | Why it happens | How agent should respond |
## Prohibited Actions
The agent MUST NEVER:
| Action | Rationale |
|--------|-----------|
| Prohibited action 1 | Why it's prohibited |
| Prohibited action 2 | Why it's prohibited |
| Prohibited action 3 | Why it's prohibited |
## Related Patterns
- [related-agent](../related-agent/AGENTS.md) - For similar tasks
- [complementary-skill](../../skills/complementary/SKILL.md) - Use together
- [workflow-pattern](../../workflows/related-workflow/SKILL.md) - Part of this workflow
## References
- [Documentation or source](https://example.com)
- For policy requirements, see [AGENTS.md](../../AGENTS.md)
- For security controls, see [playbook](https://github.com/GSA-TTS/agentic-coding-playbook)