microsoft/hve-core
Publicmirrored from https://github.com/microsoft/hve-coreAvailable
docs/contributing/custom-agents.md
421lines · modecode
| 1 | --- |
| 2 | title: 'Contributing Agents to HVE Core' |
| 3 | description: 'Requirements and standards for contributing GitHub Copilot agent files to hve-core' |
| 4 | author: Microsoft |
| 5 | ms.date: 2025-11-26 |
| 6 | ms.topic: how-to |
| 7 | --- |
| 8 | |
| 9 | This guide defines the requirements, standards, and best practices for contributing GitHub Copilot agent files (`.agent.md`) to the hve-core library. |
| 10 | |
| 11 | **⚙️ Common Standards**: See [AI Artifacts Common Standards](ai-artifacts-common.md) for shared requirements (XML blocks, markdown quality, RFC 2119, validation, testing). |
| 12 | |
| 13 | ## What is an Agent? |
| 14 | |
| 15 | An **agent** is a specialized AI configuration that defines behavior, available tools, and instructions for GitHub Copilot to follow when performing specific tasks. Agents enable consistent, repeatable workflows for complex development activities. |
| 16 | |
| 17 | ## Use Cases for Agents |
| 18 | |
| 19 | Create an agent when you need to: |
| 20 | |
| 21 | * Define a specialized AI agent role (e.g., security reviewer, PR analyzer, documentation generator) |
| 22 | * Orchestrate multi-step workflows requiring specific tool sequences |
| 23 | * Maintain consistent behavior patterns across development tasks |
| 24 | * Provide domain-specific expertise (e.g., ADR creation, work item processing) |
| 25 | * Automate complex decision-making with predefined logic flows |
| 26 | |
| 27 | ## Agents Not Accepted |
| 28 | |
| 29 | The following agent types will likely be **rejected or closed automatically** because **equivalent agents already exist in hve-core**: |
| 30 | |
| 31 | ### Duplicate Agent Categories |
| 32 | |
| 33 | * **Research or Discovery Agents**: Agents that search for, gather, or discover information |
| 34 | * ❌ Reason: Existing agents already handle research and discovery workflows |
| 35 | * ✅ Alternative: Use existing research-focused agents in `.github/agents/` |
| 36 | |
| 37 | * **Indexing or Referencing Agents**: Agents that catalog, index, or create references to existing projects |
| 38 | * ❌ Reason: Existing agents already provide indexing and referencing capabilities |
| 39 | * ❌ Tool integration: Widely supported tools built into VS Code GitHub Copilot and MCP tools with extremely wide adoption are already supported by existing hve-core agents |
| 40 | * ✅ Alternative: Use existing reference management agents that leverage standard VS Code GitHub Copilot tools and widely-adopted MCP tools |
| 41 | |
| 42 | * **Planning Agents**: Agents that plan work, break down tasks, or organize backlog items |
| 43 | * ❌ Reason: Existing agents already handle work planning and task organization |
| 44 | * ✅ Alternative: Use existing planning-focused agents in `.github/agents/` |
| 45 | |
| 46 | * **Implementation Agents**: General-purpose coding agents that implement features |
| 47 | * ❌ Reason: Existing agents already provide implementation guidance |
| 48 | * ✅ Alternative: Use existing implementation-focused agents |
| 49 | |
| 50 | ### Rationale for Rejection |
| 51 | |
| 52 | These agent types are rejected because: |
| 53 | |
| 54 | 1. **Existing agents are hardened and heavily utilized**: The hve-core library already contains production-tested agents in these categories |
| 55 | 2. **Consistency and maintenance**: Coalescing around existing agents reduces fragmentation and maintenance burden |
| 56 | 3. **Avoid duplication**: Multiple agents serving the same purpose create confusion and divergent behavior |
| 57 | 4. **Standard tooling already integrated**: VS Code GitHub Copilot built-in tools and widely-adopted MCP tools are already leveraged by existing agents |
| 58 | |
| 59 | ### Before Submitting |
| 60 | |
| 61 | When planning to submit an agent that falls into these categories: |
| 62 | |
| 63 | 1. **Question necessity**: Does your use case truly require a new agent, or can existing agents meet your needs? |
| 64 | 2. **Review existing agents**: Examine `.github/agents/` to identify agents that already serve your purpose |
| 65 | 3. **Check tool integration**: Verify whether the VS Code GitHub Copilot tools or MCP tools you need are already used by existing agents |
| 66 | 4. **Consider enhancement over creation**: If existing agents don't fully meet your requirements, evaluate whether your changes are: |
| 67 | * **Generic enough** to benefit all users |
| 68 | * **Valuable enough** to justify modifying the existing agent |
| 69 | 5. **Propose enhancements**: Submit a PR to enhance an existing agent rather than creating a duplicate |
| 70 | |
| 71 | ### What Makes a Good New Agent |
| 72 | |
| 73 | Focus on agents that: |
| 74 | |
| 75 | * **Fill gaps**: Address use cases not covered by existing agents |
| 76 | * **Provide unique value**: Offer specialized domain expertise or workflow patterns not present in the library |
| 77 | * **Are non-overlapping**: Have clearly distinct purposes from existing agents |
| 78 | * **Cannot be merged**: Represent functionality too specialized or divergent to integrate into existing agents |
| 79 | * **Use standard tooling**: Leverage widely-supported VS Code GitHub Copilot tools and MCP tools rather than custom integrations |
| 80 | |
| 81 | ### Model Version Requirements |
| 82 | |
| 83 | All agents **MUST** target the **latest available models** from **Anthropic and OpenAI only**. |
| 84 | |
| 85 | **Accepted**: Latest Claude models (e.g., Claude Sonnet 4, Claude Opus 4) and latest GPT models (e.g., GPT-5.1, o1) |
| 86 | |
| 87 | **Not Accepted**: Older model versions (e.g., GPT-3.5, GPT-4.1, Claude 2), models from other providers, custom/fine-tuned models |
| 88 | |
| 89 | **Rationale**: Latest models provide superior capabilities, reduce maintenance burden, and ensure future compatibility. Older model versions will be deprecated. |
| 90 | |
| 91 | ## File Structure Requirements |
| 92 | |
| 93 | ### Location |
| 94 | |
| 95 | All agent files **MUST** be placed in: |
| 96 | |
| 97 | ```text |
| 98 | .github/agents/ |
| 99 | └── your-agent-name.agent.md |
| 100 | ``` |
| 101 | |
| 102 | ### Naming Convention |
| 103 | |
| 104 | * Use lowercase kebab-case: `security-reviewer.agent.md` |
| 105 | * Be descriptive and action-oriented: `task-planner.agent.md`, `pr-review.agent.md`, `rpi-agent.agent.md` |
| 106 | * Avoid generic names: `helper.agent.md` ❌ → `ado-work-item-processor.agent.md` ✅ |
| 107 | |
| 108 | ### File Format |
| 109 | |
| 110 | Agent files **MUST**: |
| 111 | |
| 112 | 1. Use the `.agent.md` extension |
| 113 | 2. Start with valid YAML frontmatter between `---` delimiters |
| 114 | 3. Begin content directly after frontmatter |
| 115 | 4. End with single newline character |
| 116 | |
| 117 | ## Frontmatter Requirements |
| 118 | |
| 119 | ### Required Fields |
| 120 | |
| 121 | **`description`** (string, MANDATORY) |
| 122 | |
| 123 | * **Purpose**: Concise explanation of agent functionality |
| 124 | * **Format**: Single sentence, 10-200 characters |
| 125 | * **Style**: Sentence case with proper punctuation |
| 126 | * **Example**: `'Validates contributed content for quality and compliance with hve-core standards'` |
| 127 | |
| 128 | **`maturity`** (string enum, MANDATORY) |
| 129 | |
| 130 | * **Purpose**: Controls which extension channel includes this agent |
| 131 | * **Valid values**: |
| 132 | * `stable` - Production-ready, included in Stable and Pre-release channels |
| 133 | * `preview` - Feature-complete, included in Pre-release channel only |
| 134 | * `experimental` - Early development, included in Pre-release channel only |
| 135 | * `deprecated` - Scheduled for removal, excluded from all channels |
| 136 | * **Default**: New agents should use `stable` unless targeting early adopters |
| 137 | * **Example**: `stable` |
| 138 | |
| 139 | ### Optional Fields |
| 140 | |
| 141 | **`tools`** (array of strings) |
| 142 | |
| 143 | * **Purpose**: Lists GitHub Copilot tools available to this agent |
| 144 | * **Format**: Array of valid tool names in logical order (read before write) |
| 145 | * **Valid tools**: |
| 146 | * `codebase` - Semantic code search |
| 147 | * `search` - Grep/regex search |
| 148 | * `problems` - Error/warning diagnostics |
| 149 | * `editFiles` - File modification |
| 150 | * `changes` - Git change tracking |
| 151 | * `usages` - Symbol reference search |
| 152 | * `githubRepo` - External GitHub repository search |
| 153 | * `fetch` - Web page content retrieval |
| 154 | * `runCommands` - Terminal command execution |
| 155 | * `think` - Extended reasoning |
| 156 | * `findTestFiles` - Test file discovery |
| 157 | * `terminalLastCommand` - Terminal history |
| 158 | * `searchResults` - Search view results |
| 159 | * `edit/createFile` - File creation |
| 160 | * `edit/createDirectory` - Directory creation |
| 161 | * `Bicep (EXPERIMENTAL)/*` - Bicep tooling |
| 162 | * `terraform/*` - Terraform tooling |
| 163 | * `context7/*` - Library documentation |
| 164 | * `microsoft-docs/*` - Microsoft documentation |
| 165 | |
| 166 | **`mode`** (string enum) |
| 167 | |
| 168 | * **Purpose**: Defines agent interaction pattern |
| 169 | * **Valid values**: `agent`, `assistant`, `copilot` |
| 170 | * **Default**: Auto-detected from usage pattern |
| 171 | |
| 172 | **`version`** (string) |
| 173 | |
| 174 | * **Purpose**: Tracks agent revisions |
| 175 | * **Format**: Semantic versioning (e.g., `1.0.0`) |
| 176 | |
| 177 | **`author`** (string) |
| 178 | |
| 179 | * **Purpose**: Attribution for agent creator |
| 180 | * **Example**: `microsoft/hve-core`, `your-team-name` |
| 181 | |
| 182 | ### Frontmatter Example |
| 183 | |
| 184 | ```yaml |
| 185 | --- |
| 186 | description: 'Validates and reviews contributed agents, prompts, and instructions for quality and compliance' |
| 187 | tools: ['codebase', 'search', 'problems', 'editFiles', 'changes', 'usages'] |
| 188 | mode: 'agent' |
| 189 | version: '1.0.0' |
| 190 | author: 'microsoft/hve-core' |
| 191 | --- |
| 192 | ``` |
| 193 | |
| 194 | ## Agent Content Structure Standards |
| 195 | |
| 196 | ### Required Sections |
| 197 | |
| 198 | #### 1. Title (H1) |
| 199 | |
| 200 | * Clear, action-oriented heading matching agent purpose |
| 201 | * Should align with filename and description |
| 202 | |
| 203 | ```markdown |
| 204 | # Content Validator Agent |
| 205 | ``` |
| 206 | |
| 207 | #### 2. Overview/Role Definition |
| 208 | |
| 209 | * Explains what the agent does and when to use it |
| 210 | * Defines scope and boundaries |
| 211 | * Sets expectations for users |
| 212 | |
| 213 | ```markdown |
| 214 | You are an expert reviewer for GitHub Copilot agents, prompts, and instruction files. |
| 215 | Your mission is to ensure all contributed guidance files meet hve-core quality standards |
| 216 | before they're merged into the library. |
| 217 | ``` |
| 218 | |
| 219 | #### 3. Core Directives/Instructions |
| 220 | |
| 221 | * Uses clear, imperative language |
| 222 | * Employs RFC 2119 keywords consistently: |
| 223 | * **MUST/WILL/MANDATORY/CRITICAL** - Required behavior |
| 224 | * **SHOULD/RECOMMENDED** - Strong guidance |
| 225 | * **MAY/OPTIONAL** - Permitted but not required |
| 226 | * Provides step-by-step workflows |
| 227 | * Includes decision points and branching logic |
| 228 | |
| 229 | #### 4. Examples and Templates |
| 230 | |
| 231 | * Demonstrates correct usage patterns |
| 232 | * Shows both positive (✅) and negative (❌) examples |
| 233 | * Wraps in XML-style blocks for reusability |
| 234 | |
| 235 | #### 5. Success Criteria |
| 236 | |
| 237 | * Defines completion conditions |
| 238 | * Specifies validation checkpoints |
| 239 | * Lists quality gates |
| 240 | |
| 241 | #### 6. Attribution Footer |
| 242 | |
| 243 | * **MANDATORY**: Include at end of file |
| 244 | |
| 245 | ```markdown |
| 246 | --- |
| 247 | |
| 248 | Brought to you by microsoft/hve-core |
| 249 | ``` |
| 250 | |
| 251 | ### XML-Style Block Requirements |
| 252 | |
| 253 | See [AI Artifacts Common Standards - XML-Style Block Standards](ai-artifacts-common.md#xml-style-block-standards) for complete rules and examples. |
| 254 | |
| 255 | ### Directive Language Standards |
| 256 | |
| 257 | Use RFC 2119 compliant keywords (MUST/SHOULD/MAY). See [AI Artifacts Common Standards - RFC 2119 Directive Language](ai-artifacts-common.md#rfc-2119-directive-language) for complete guidance. |
| 258 | |
| 259 | ## Tool Usage Discipline |
| 260 | |
| 261 | When agents use tools, they **MUST** follow these patterns: |
| 262 | |
| 263 | ### Tool Usage Preambles |
| 264 | |
| 265 | Before any batch of tool calls, include a one-sentence explanation: |
| 266 | |
| 267 | ```markdown |
| 268 | **Tool Usage Preamble**: "Analyzing file structure, reading schemas, and checking |
| 269 | repository conventions to establish validation baseline." |
| 270 | ``` |
| 271 | |
| 272 | ### Checkpoints |
| 273 | |
| 274 | After 3-5 tool calls or more than 3 file edits, provide a compact checkpoint: |
| 275 | |
| 276 | ```markdown |
| 277 | **Checkpoint After Discovery**: "Identified [file type], loaded [schema name], |
| 278 | found [N] related files for comparison." |
| 279 | ``` |
| 280 | |
| 281 | ### Tool Result Integration |
| 282 | |
| 283 | * Document how tool results inform next steps |
| 284 | * Specify error handling for tool failures |
| 285 | * Justify tool selection (why this tool for this task) |
| 286 | |
| 287 | ## Output Formatting Requirements |
| 288 | |
| 289 | Define how the agent communicates with users: |
| 290 | |
| 291 | ### Response Format |
| 292 | |
| 293 | * Start all responses with: `## **[Agent Name]**: [Action Description]` |
| 294 | * Use short, action-oriented section headers |
| 295 | * Employ proper markdown formatting |
| 296 | * Include emojis for visual clarity (when appropriate) |
| 297 | |
| 298 | ### Status Reporting |
| 299 | |
| 300 | Specify formats for: |
| 301 | |
| 302 | * Progress updates |
| 303 | * Error messages |
| 304 | * Completion confirmations |
| 305 | * Validation results |
| 306 | |
| 307 | ### Requirements Checklist |
| 308 | |
| 309 | For agents performing edits or validations: |
| 310 | |
| 311 | ```markdown |
| 312 | ### Requirements Checklist |
| 313 | |
| 314 | - [x] Pre-validation analysis complete - Loaded schema, checked conventions |
| 315 | - [x] Frontmatter validation - All required fields present |
| 316 | - [ ] Technical validation - 2 broken file references found |
| 317 | ``` |
| 318 | |
| 319 | ### Quality Gates |
| 320 | |
| 321 | Report validation status: |
| 322 | |
| 323 | ```markdown |
| 324 | ### Quality Gates |
| 325 | |
| 326 | - **Build**: PASS |
| 327 | - **Lint**: FAIL - Markdownlint flagged: bare URLs (lines 45, 67) |
| 328 | - **Schema**: PASS - Frontmatter validates |
| 329 | ``` |
| 330 | |
| 331 | ## Research and External Sources |
| 332 | |
| 333 | When agents integrate external knowledge, consult authoritative sources and provide minimal, annotated snippets with reference links. See [AI Artifacts Common Standards - Attribution Requirements](ai-artifacts-common.md#attribution-requirements) for guidelines. |
| 334 | |
| 335 | ## Validation Checklist |
| 336 | |
| 337 | Before submitting your agent, verify: |
| 338 | |
| 339 | ### Frontmatter |
| 340 | |
| 341 | * [ ] Valid YAML between `---` delimiters |
| 342 | * [ ] `description` field present and descriptive (10-200 chars) |
| 343 | * [ ] `tools` array contains only valid tool names (if present) |
| 344 | * [ ] `mode` is one of: `agent`, `assistant`, `copilot` (if present) |
| 345 | * [ ] No trailing whitespace in values |
| 346 | * [ ] Single newline at EOF |
| 347 | |
| 348 | ### Content Structure |
| 349 | |
| 350 | * [ ] Clear H1 title matching purpose |
| 351 | * [ ] Overview/role definition section |
| 352 | * [ ] Core directives with RFC 2119 keywords |
| 353 | * [ ] Examples wrapped in XML-style blocks |
| 354 | * [ ] Success criteria defined |
| 355 | * [ ] Attribution footer present |
| 356 | |
| 357 | ### Common Standards |
| 358 | |
| 359 | * [ ] Markdown quality (see [Common Standards - Markdown Quality](ai-artifacts-common.md#markdown-quality-standards)) |
| 360 | * [ ] XML-style blocks properly formatted (see [Common Standards - XML-Style Blocks](ai-artifacts-common.md#xml-style-block-standards)) |
| 361 | * [ ] RFC 2119 keywords used consistently (see [Common Standards - RFC 2119](ai-artifacts-common.md#rfc-2119-directive-language)) |
| 362 | |
| 363 | ### Technical Validation |
| 364 | |
| 365 | * [ ] All file references point to existing files |
| 366 | * [ ] External links are valid and accessible |
| 367 | * [ ] Tool names in frontmatter are correct |
| 368 | * [ ] No conflicts with existing agents |
| 369 | |
| 370 | ### Integration |
| 371 | |
| 372 | * [ ] Aligns with `.github/copilot-instructions.md` |
| 373 | * [ ] Follows repository conventions |
| 374 | * [ ] Compatible with existing workflows |
| 375 | * [ ] Does not duplicate existing agent functionality |
| 376 | |
| 377 | ## Testing Your Agent |
| 378 | |
| 379 | See [AI Artifacts Common Standards - Common Testing Practices](ai-artifacts-common.md#common-testing-practices) for testing guidelines. For agents specifically: |
| 380 | |
| 381 | 1. Test with realistic scenarios matching the agent's purpose |
| 382 | 2. Verify tool usage patterns execute correctly |
| 383 | 3. Ensure decision points and branching logic work as intended |
| 384 | 4. Check edge cases: missing data, invalid inputs, tool failures |
| 385 | |
| 386 | ## Common Issues and Fixes |
| 387 | |
| 388 | ### Agent-Specific Issues |
| 389 | |
| 390 | ### Invalid Tool Names |
| 391 | |
| 392 | * **Problem**: Referencing tools that don't exist or using incorrect camelCase variants |
| 393 | * **Solution**: Use exact tool names from VS Code Copilot's available tools list |
| 394 | |
| 395 | For additional common issues (XML blocks, markdown, directives), see [AI Artifacts Common Standards - Common Issues and Fixes](ai-artifacts-common.md#common-issues-and-fixes). |
| 396 | |
| 397 | ## Automated Validation |
| 398 | |
| 399 | Run these commands before submission (see [Common Standards - Common Validation](ai-artifacts-common.md#common-validation-standards)): |
| 400 | |
| 401 | * `npm run lint:frontmatter` |
| 402 | * `npm run lint:md` |
| 403 | * `npm run spell-check` |
| 404 | * `npm run lint:md-links` |
| 405 | |
| 406 | All checks **MUST** pass before merge. |
| 407 | |
| 408 | ## Related Documentation |
| 409 | |
| 410 | * [AI Artifacts Common Standards](ai-artifacts-common.md) - Shared standards for all contributions |
| 411 | * [Contributing Prompts](prompts.md) - Workflow-specific guidance files |
| 412 | * [Contributing Instructions](instructions.md) - Technology-specific standards |
| 413 | * [Pull Request Template](../../.github/PULL_REQUEST_TEMPLATE.md) - Submission requirements |
| 414 | |
| 415 | ## Getting Help |
| 416 | |
| 417 | See [AI Artifacts Common Standards - Getting Help](ai-artifacts-common.md#getting-help) for support resources. For agent-specific assistance, review existing examples in `.github/agents/`. |
| 418 | |
| 419 | --- |
| 420 | |
| 421 | Brought to you by microsoft/hve-core |
| 422 | |