microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/contributing/custom-agents.md
493lines · 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 | ### Optional Fields |
| 129 | |
| 130 | **`tools`** (array of strings) |
| 131 | |
| 132 | * **Purpose**: Lists GitHub Copilot tools available to this agent |
| 133 | * **Format**: Array of valid tool names in logical order (read before write) |
| 134 | * **Valid tools**: |
| 135 | * `codebase` - Semantic code search |
| 136 | * `search` - Grep/regex search |
| 137 | * `problems` - Error/warning diagnostics |
| 138 | * `editFiles` - File modification |
| 139 | * `changes` - Git change tracking |
| 140 | * `usages` - Symbol reference search |
| 141 | * `githubRepo` - External GitHub repository search |
| 142 | * `fetch` - Web page content retrieval |
| 143 | * `runCommands` - Terminal command execution |
| 144 | * `think` - Extended reasoning |
| 145 | * `findTestFiles` - Test file discovery |
| 146 | * `terminalLastCommand` - Terminal history |
| 147 | * `searchResults` - Search view results |
| 148 | * `edit/createFile` - File creation |
| 149 | * `edit/createDirectory` - Directory creation |
| 150 | * `Bicep (EXPERIMENTAL)/*` - Bicep tooling |
| 151 | * `terraform/*` - Terraform tooling |
| 152 | * `context7/*` - Library documentation |
| 153 | * `microsoft-docs/*` - Microsoft documentation |
| 154 | |
| 155 | **`mode`** (string enum) |
| 156 | |
| 157 | * **Purpose**: Defines agent interaction pattern |
| 158 | * **Valid values**: `agent`, `assistant`, `copilot` |
| 159 | * **Default**: Auto-detected from usage pattern |
| 160 | |
| 161 | **`version`** (string) |
| 162 | |
| 163 | * **Purpose**: Tracks agent revisions |
| 164 | * **Format**: Semantic versioning (e.g., `1.0.0`) |
| 165 | |
| 166 | **`author`** (string) |
| 167 | |
| 168 | * **Purpose**: Attribution for agent creator |
| 169 | * **Example**: `microsoft/hve-core`, `your-team-name` |
| 170 | |
| 171 | **`handoffs`** (array of objects) |
| 172 | |
| 173 | * **Purpose**: Declares agent-to-agent handoff buttons that appear in the chat UI |
| 174 | * **Format**: Array of handoff declarations |
| 175 | * **Fields per handoff**: |
| 176 | * `label` (string, required): Button text displayed in UI, supports emoji |
| 177 | * `agent` (string, required): Target agent filename without `.agent.md` extension |
| 178 | * `prompt` (string, optional): Pre-filled prompt text, can include slash commands |
| 179 | * `send` (boolean, optional): When true, auto-submits prompt; when false (default), user can edit |
| 180 | * **Requirements**: VS Code 1.106+ required for handoff support |
| 181 | * **Example**: |
| 182 | |
| 183 | ```yaml |
| 184 | handoffs: |
| 185 | - label: "📋 Create Plan" |
| 186 | agent: task-planner |
| 187 | prompt: /task-plan |
| 188 | send: true |
| 189 | ``` |
| 190 | |
| 191 | ### Frontmatter Example |
| 192 | |
| 193 | ```yaml |
| 194 | --- |
| 195 | description: 'Validates and reviews contributed agents, prompts, and instructions for quality and compliance' |
| 196 | tools: ['codebase', 'search', 'problems', 'editFiles', 'changes', 'usages'] |
| 197 | mode: 'agent' |
| 198 | version: '1.0.0' |
| 199 | author: 'microsoft/hve-core' |
| 200 | --- |
| 201 | ``` |
| 202 | |
| 203 | ## Collection Entry Requirements |
| 204 | |
| 205 | All agents must have matching entries in one or more `collections/*.collection.yml` manifests. Collection entries control selection and maturity. |
| 206 | |
| 207 | ### Adding Your Agent to a Collection |
| 208 | |
| 209 | After creating your agent file, add an `items[]` entry to each target collection: |
| 210 | |
| 211 | ```yaml |
| 212 | items: |
| 213 | - path: .github/agents/my-new-agent.agent.md |
| 214 | kind: agent |
| 215 | maturity: stable |
| 216 | ``` |
| 217 | |
| 218 | ### Selecting Collections for Agents |
| 219 | |
| 220 | Choose collections based on who benefits most from your agent: |
| 221 | |
| 222 | | Agent Type | Recommended Collections | |
| 223 | |----------------------|-------------------------------------------| |
| 224 | | Task workflow agents | `hve-core-all`, `rpi` | |
| 225 | | Architecture agents | `hve-core-all`, `project-planning` | |
| 226 | | Documentation agents | `hve-core-all`, `prompt-engineering` | |
| 227 | | Data science agents | `hve-core-all`, `data-science` | |
| 228 | | ADO/work item agents | `hve-core-all`, `ado`, `project-planning` | |
| 229 | | Code review agents | `hve-core-all`, `coding-standards` | |
| 230 | |
| 231 | ### Declaring Agent Dependencies |
| 232 | |
| 233 | If your agent dispatches other agents at runtime via `runSubagent`, invokes prompts, or depends on skills, document those relationships in the agent content and validate packaging behavior in affected collections. |
| 234 | |
| 235 | For complete collection documentation, see [AI Artifacts Common Standards - Collection Manifests](ai-artifacts-common.md#collection-manifests). |
| 236 | |
| 237 | ### MCP Tool Dependencies |
| 238 | |
| 239 | When agents reference MCP tools in their `tools:` frontmatter or body content, document the dependencies clearly. |
| 240 | |
| 241 | **Frontmatter declaration:** |
| 242 | |
| 243 | ```yaml |
| 244 | tools: ['github/*', 'ado/*', 'context7/*', 'microsoft-docs/*'] |
| 245 | ``` |
| 246 | |
| 247 | **Curated MCP servers referenced by HVE-Core agents:** |
| 248 | |
| 249 | | Server | Tool Pattern | Purpose | |
| 250 | |----------------|--------------------|-------------------------------------------| |
| 251 | | github | `github/*` | GitHub repository and issue management | |
| 252 | | ado | `ado/*` | Azure DevOps work items, pipelines, repos | |
| 253 | | context7 | `context7/*` | Library and SDK documentation lookup | |
| 254 | | microsoft-docs | `microsoft-docs/*` | Microsoft Learn documentation | |
| 255 | |
| 256 | **Guidelines for MCP tool references:** |
| 257 | |
| 258 | * Document MCP dependencies in agent body text when using `mcp_*` tool patterns |
| 259 | * Agents should gracefully handle missing MCP servers (tools unavailable) |
| 260 | * Reference the [MCP Server Configuration](../getting-started/mcp-configuration.md) guide when agents require MCP tools |
| 261 | * Prefer built-in VS Code Copilot tools when equivalent functionality exists |
| 262 | |
| 263 | ## Agent Content Structure Standards |
| 264 | |
| 265 | ### Required Sections |
| 266 | |
| 267 | #### 1. Title (H1) |
| 268 | |
| 269 | * Clear, action-oriented heading matching agent purpose |
| 270 | * Should align with filename and description |
| 271 | |
| 272 | ```markdown |
| 273 | # Content Validator Agent |
| 274 | ``` |
| 275 | |
| 276 | #### 2. Overview/Role Definition |
| 277 | |
| 278 | * Explains what the agent does and when to use it |
| 279 | * Defines scope and boundaries |
| 280 | * Sets expectations for users |
| 281 | |
| 282 | ```markdown |
| 283 | You are an expert reviewer for GitHub Copilot agents, prompts, and instruction files. |
| 284 | Your mission is to ensure all contributed guidance files meet hve-core quality standards |
| 285 | before they're merged into the library. |
| 286 | ``` |
| 287 | |
| 288 | #### 3. Core Directives/Instructions |
| 289 | |
| 290 | * Uses clear, imperative language |
| 291 | * Employs RFC 2119 keywords consistently: |
| 292 | * **MUST/WILL/MANDATORY/CRITICAL** - Required behavior |
| 293 | * **SHOULD/RECOMMENDED** - Strong guidance |
| 294 | * **MAY/OPTIONAL** - Permitted but not required |
| 295 | * Provides step-by-step workflows |
| 296 | * Includes decision points and branching logic |
| 297 | |
| 298 | #### 4. Examples and Templates |
| 299 | |
| 300 | * Demonstrates correct usage patterns |
| 301 | * Shows both positive (✅) and negative (❌) examples |
| 302 | * Wraps in XML-style blocks for reusability |
| 303 | |
| 304 | #### 5. Success Criteria |
| 305 | |
| 306 | * Defines completion conditions |
| 307 | * Specifies validation checkpoints |
| 308 | * Lists quality gates |
| 309 | |
| 310 | #### 6. Attribution Footer |
| 311 | |
| 312 | * **MANDATORY**: Include at end of file |
| 313 | |
| 314 | ```markdown |
| 315 | --- |
| 316 | |
| 317 | Brought to you by microsoft/hve-core |
| 318 | ``` |
| 319 | |
| 320 | ### XML-Style Block Requirements |
| 321 | |
| 322 | See [AI Artifacts Common Standards - XML-Style Block Standards](ai-artifacts-common.md#xml-style-block-standards) for complete rules and examples. |
| 323 | |
| 324 | ### Directive Language Standards |
| 325 | |
| 326 | 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. |
| 327 | |
| 328 | ## Tool Usage Discipline |
| 329 | |
| 330 | When agents use tools, they **MUST** follow these patterns: |
| 331 | |
| 332 | ### Tool Usage Preambles |
| 333 | |
| 334 | Before any batch of tool calls, include a one-sentence explanation: |
| 335 | |
| 336 | ```markdown |
| 337 | **Tool Usage Preamble**: "Analyzing file structure, reading schemas, and checking |
| 338 | repository conventions to establish validation baseline." |
| 339 | ``` |
| 340 | |
| 341 | ### Checkpoints |
| 342 | |
| 343 | After 3-5 tool calls or more than 3 file edits, provide a compact checkpoint: |
| 344 | |
| 345 | ```markdown |
| 346 | **Checkpoint After Discovery**: "Identified [file type], loaded [schema name], |
| 347 | found [N] related files for comparison." |
| 348 | ``` |
| 349 | |
| 350 | ### Tool Result Integration |
| 351 | |
| 352 | * Document how tool results inform next steps |
| 353 | * Specify error handling for tool failures |
| 354 | * Justify tool selection (why this tool for this task) |
| 355 | |
| 356 | ## Output Formatting Requirements |
| 357 | |
| 358 | Define how the agent communicates with users: |
| 359 | |
| 360 | ### Response Format |
| 361 | |
| 362 | * Start all responses with: `## **[Agent Name]**: [Action Description]` |
| 363 | * Use short, action-oriented section headers |
| 364 | * Employ proper markdown formatting |
| 365 | * Include emojis for visual clarity (when appropriate) |
| 366 | |
| 367 | ### Status Reporting |
| 368 | |
| 369 | Specify formats for: |
| 370 | |
| 371 | * Progress updates |
| 372 | * Error messages |
| 373 | * Completion confirmations |
| 374 | * Validation results |
| 375 | |
| 376 | ### Requirements Checklist |
| 377 | |
| 378 | For agents performing edits or validations: |
| 379 | |
| 380 | ```markdown |
| 381 | ### Requirements Checklist |
| 382 | |
| 383 | - [x] Pre-validation analysis complete - Loaded schema, checked conventions |
| 384 | - [x] Frontmatter validation - All required fields present |
| 385 | - [ ] Technical validation - 2 broken file references found |
| 386 | ``` |
| 387 | |
| 388 | ### Quality Gates |
| 389 | |
| 390 | Report validation status: |
| 391 | |
| 392 | ```markdown |
| 393 | ### Quality Gates |
| 394 | |
| 395 | - **Build**: PASS |
| 396 | - **Lint**: FAIL - Markdownlint flagged: bare URLs (lines 45, 67) |
| 397 | - **Schema**: PASS - Frontmatter validates |
| 398 | ``` |
| 399 | |
| 400 | ## Research and External Sources |
| 401 | |
| 402 | 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. |
| 403 | |
| 404 | ## Validation Checklist |
| 405 | |
| 406 | Before submitting your agent, verify: |
| 407 | |
| 408 | ### Frontmatter |
| 409 | |
| 410 | * [ ] Valid YAML between `---` delimiters |
| 411 | * [ ] `description` field present and descriptive (10-200 chars) |
| 412 | * [ ] `tools` array contains only valid tool names (if present) |
| 413 | * [ ] `mode` is one of: `agent`, `assistant`, `copilot` (if present) |
| 414 | * [ ] No trailing whitespace in values |
| 415 | * [ ] Single newline at EOF |
| 416 | |
| 417 | ### Content Structure |
| 418 | |
| 419 | * [ ] Clear H1 title matching purpose |
| 420 | * [ ] Overview/role definition section |
| 421 | * [ ] Core directives with RFC 2119 keywords |
| 422 | * [ ] Examples wrapped in XML-style blocks |
| 423 | * [ ] Success criteria defined |
| 424 | * [ ] Attribution footer present |
| 425 | |
| 426 | ### Common Standards |
| 427 | |
| 428 | * [ ] Markdown quality (see [Common Standards - Markdown Quality](ai-artifacts-common.md#markdown-quality-standards)) |
| 429 | * [ ] XML-style blocks properly formatted (see [Common Standards - XML-Style Blocks](ai-artifacts-common.md#xml-style-block-standards)) |
| 430 | * [ ] RFC 2119 keywords used consistently (see [Common Standards - RFC 2119](ai-artifacts-common.md#rfc-2119-directive-language)) |
| 431 | |
| 432 | ### Technical Validation |
| 433 | |
| 434 | * [ ] All file references point to existing files |
| 435 | * [ ] External links are valid and accessible |
| 436 | * [ ] Tool names in frontmatter are correct |
| 437 | * [ ] No conflicts with existing agents |
| 438 | |
| 439 | ### Integration |
| 440 | |
| 441 | * [ ] Aligns with `.github/copilot-instructions.md` |
| 442 | * [ ] Follows repository conventions |
| 443 | * [ ] Compatible with existing workflows |
| 444 | * [ ] Does not duplicate existing agent functionality |
| 445 | |
| 446 | ## Testing Your Agent |
| 447 | |
| 448 | See [AI Artifacts Common Standards - Common Testing Practices](ai-artifacts-common.md#common-testing-practices) for testing guidelines. For agents specifically: |
| 449 | |
| 450 | 1. Test with realistic scenarios matching the agent's purpose |
| 451 | 2. Verify tool usage patterns execute correctly |
| 452 | 3. Ensure decision points and branching logic work as intended |
| 453 | 4. Check edge cases: missing data, invalid inputs, tool failures |
| 454 | |
| 455 | ## Common Issues and Fixes |
| 456 | |
| 457 | ### Agent-Specific Issues |
| 458 | |
| 459 | ### Invalid Tool Names |
| 460 | |
| 461 | * **Problem**: Referencing tools that don't exist or using incorrect camelCase variants |
| 462 | * **Solution**: Use exact tool names from VS Code Copilot's available tools list |
| 463 | |
| 464 | 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). |
| 465 | |
| 466 | ## Automated Validation |
| 467 | |
| 468 | Run these commands before submission (see [Common Standards - Common Validation](ai-artifacts-common.md#common-validation-standards)): |
| 469 | |
| 470 | * `npm run lint:frontmatter` |
| 471 | * `npm run lint:md` |
| 472 | * `npm run spell-check` |
| 473 | * `npm run lint:md-links` |
| 474 | |
| 475 | All checks **MUST** pass before merge. |
| 476 | |
| 477 | ## Related Documentation |
| 478 | |
| 479 | * [AI Artifacts Common Standards](ai-artifacts-common.md) - Shared standards for all contributions |
| 480 | * [Contributing Prompts](prompts.md) - Workflow-specific guidance files |
| 481 | * [Contributing Instructions](instructions.md) - Technology-specific standards |
| 482 | * [Pull Request Template](../../.github/PULL_REQUEST_TEMPLATE.md) - Submission requirements |
| 483 | |
| 484 | ## Getting Help |
| 485 | |
| 486 | 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/`. |
| 487 | |
| 488 | --- |
| 489 | |
| 490 | <!-- markdownlint-disable MD036 --> |
| 491 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 492 | then carefully refined by our team of discerning human reviewers.* |
| 493 | <!-- markdownlint-enable MD036 --> |
| 494 | |