microsoft/hve-core
Publicmirrored from https://github.com/microsoft/hve-coreAvailable
docs/contributing/custom-agents.md
580lines · 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 |
| 34 | |
| 35 | Agents that search for, gather, or discover information. |
| 36 | |
| 37 | * ❌ Reason: Existing agents already handle research and discovery workflows |
| 38 | * ✅ Alternative: Use existing research-focused agents in `.github/agents/` |
| 39 | |
| 40 | #### Indexing or Referencing Agents |
| 41 | |
| 42 | Agents that catalog, index, or create references to existing projects. |
| 43 | |
| 44 | * ❌ Reason: Existing agents already provide indexing and referencing capabilities |
| 45 | * ❌ 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 |
| 46 | * ✅ Alternative: Use existing reference management agents that use standard VS Code GitHub Copilot tools and widely-adopted MCP tools |
| 47 | |
| 48 | #### Planning Agents |
| 49 | |
| 50 | Agents that plan work, break down tasks, or organize backlog items. |
| 51 | |
| 52 | * ❌ Reason: Existing agents already handle work planning and task organization |
| 53 | * ✅ Alternative: Use existing planning-focused agents in `.github/agents/` |
| 54 | |
| 55 | #### Implementation Agents |
| 56 | |
| 57 | General-purpose coding agents that implement features. |
| 58 | |
| 59 | * ❌ Reason: Existing agents already provide implementation guidance |
| 60 | * ✅ Alternative: Use existing implementation-focused agents |
| 61 | |
| 62 | ### Rationale for Rejection |
| 63 | |
| 64 | These agent types are rejected because: |
| 65 | |
| 66 | 1. Existing agents are hardened and heavily used — the hve-core library already contains production-tested agents in these categories |
| 67 | 2. Consistency and maintenance — coalescing around existing agents reduces fragmentation and maintenance burden |
| 68 | 3. Avoid duplication — multiple agents serving the same purpose create confusion and divergent behavior |
| 69 | 4. Standard tooling already integrated — VS Code GitHub Copilot built-in tools and widely-adopted MCP tools are already used by existing agents |
| 70 | |
| 71 | ### Before Submitting |
| 72 | |
| 73 | When planning to submit an agent that falls into these categories: |
| 74 | |
| 75 | 1. Question necessity — does your use case truly require a new agent, or can existing agents meet your needs? |
| 76 | 2. Review existing agents — examine `.github/agents/` to identify agents that already serve your purpose |
| 77 | 3. Check tool integration — verify whether the VS Code GitHub Copilot tools or MCP tools you need are already used by existing agents |
| 78 | 4. Consider enhancement over creation — if existing agents don't fully meet your requirements, evaluate whether your changes are generic enough to benefit all users and valuable enough to justify modifying the existing agent |
| 79 | 5. Propose enhancements — submit a PR to enhance an existing agent rather than creating a duplicate |
| 80 | |
| 81 | ### What Makes a Good New Agent |
| 82 | |
| 83 | Focus on agents that: |
| 84 | |
| 85 | | Criterion | Description | |
| 86 | |----------------------|-------------------------------------------------------------------------------------------------| |
| 87 | | Fill gaps | Address use cases not covered by existing agents | |
| 88 | | Provide unique value | Offer specialized domain expertise or workflow patterns not present in the library | |
| 89 | | Are non-overlapping | Have clearly distinct purposes from existing agents | |
| 90 | | Cannot be merged | Represent functionality too specialized or divergent to integrate into existing agents | |
| 91 | | Use standard tooling | Use widely-supported VS Code GitHub Copilot tools and MCP tools rather than custom integrations | |
| 92 | |
| 93 | ### Model Version Requirements |
| 94 | |
| 95 | All agents **MUST** target the **latest available models** from **Anthropic and OpenAI only**. |
| 96 | |
| 97 | **Accepted**: Latest Claude models (e.g., Claude Sonnet 4, Claude Opus 4) and latest GPT models (e.g., GPT-5.1, o1) |
| 98 | |
| 99 | **Not Accepted**: Older model versions (e.g., GPT-3.5, GPT-4.1, Claude 2), models from other providers, custom/fine-tuned models |
| 100 | |
| 101 | **Rationale**: Latest models provide superior capabilities, reduce maintenance burden, and ensure future compatibility. Older model versions will be deprecated. |
| 102 | |
| 103 | ## File Structure Requirements |
| 104 | |
| 105 | ### Location |
| 106 | |
| 107 | Agent files are typically organized in a collection subdirectory by convention: |
| 108 | |
| 109 | ```text |
| 110 | .github/agents/{collection-id}/ |
| 111 | ├── your-agent-name.agent.md |
| 112 | └── subagents/ |
| 113 | └── your-subagent-name.agent.md |
| 114 | ``` |
| 115 | |
| 116 | > [!NOTE] |
| 117 | > Collections can reference artifacts from any subfolder. The `path:` field in collection YAML files |
| 118 | > accepts any valid repo-relative path regardless of the artifact's parent directory. |
| 119 | |
| 120 | ### Naming Convention |
| 121 | |
| 122 | * Use lowercase kebab-case: `security-reviewer.agent.md` |
| 123 | * Be descriptive and action-oriented: `task-planner.agent.md`, `pr-review.agent.md`, `rpi-agent.agent.md` |
| 124 | * Avoid generic names: `helper.agent.md` ❌ → `ado-work-item-processor.agent.md` ✅ |
| 125 | |
| 126 | ### File Format |
| 127 | |
| 128 | Agent files **MUST**: |
| 129 | |
| 130 | 1. Use the `.agent.md` extension |
| 131 | 2. Start with valid YAML frontmatter between `---` delimiters |
| 132 | 3. Begin content directly after frontmatter |
| 133 | 4. End with single newline character |
| 134 | |
| 135 | ## Frontmatter Requirements |
| 136 | |
| 137 | ### Required Fields |
| 138 | |
| 139 | **`description`** (string, MANDATORY) |
| 140 | |
| 141 | | Attribute | Details | |
| 142 | |-----------|--------------------------------------------------------------------------------------| |
| 143 | | Purpose | Concise explanation of agent functionality | |
| 144 | | Format | Single sentence, 10-200 characters | |
| 145 | | Style | Sentence case with proper punctuation | |
| 146 | | Example | `'Validates contributed content for quality and compliance with hve-core standards'` | |
| 147 | |
| 148 | ### Optional Fields |
| 149 | |
| 150 | **`name`** (string) |
| 151 | |
| 152 | | Attribute | Details | |
| 153 | |-----------|----------------------------------------------------------| |
| 154 | | Purpose | Custom display name for the agent | |
| 155 | | Format | Lowercase kebab-case matching filename without extension | |
| 156 | | Default | File name used if not specified | |
| 157 | |
| 158 | **`tools`** (array of strings) |
| 159 | |
| 160 | | Attribute | Details | |
| 161 | |-----------|----------------------------------------------------------------| |
| 162 | | Purpose | Lists GitHub Copilot tools available to this agent | |
| 163 | | Format | Array of valid tool names in logical order (read before write) | |
| 164 | |
| 165 | Valid tools: |
| 166 | |
| 167 | * `codebase` - Semantic code search |
| 168 | * `search` - Grep/regex search |
| 169 | * `problems` - Error/warning diagnostics |
| 170 | * `editFiles` - File modification |
| 171 | * `changes` - Git change tracking |
| 172 | * `usages` - Symbol reference search |
| 173 | * `githubRepo` - External GitHub repository search |
| 174 | * `fetch` - Web page content retrieval |
| 175 | * `runCommands` - Terminal command execution |
| 176 | * `think` - Extended reasoning |
| 177 | * `findTestFiles` - Test file discovery |
| 178 | * `terminalLastCommand` - Terminal history |
| 179 | * `searchResults` - Search view results |
| 180 | * `edit/createFile` - File creation |
| 181 | * `edit/createDirectory` - Directory creation |
| 182 | * `Bicep (EXPERIMENTAL)/*` - Bicep tooling |
| 183 | * `terraform/*` - Terraform tooling |
| 184 | * `context7/*` - Library documentation |
| 185 | * `microsoft-docs/*` - Microsoft documentation |
| 186 | |
| 187 | **`agents`** (array of strings) |
| 188 | |
| 189 | | Attribute | Details | |
| 190 | |-------------|------------------------------------------------------------------------------------| |
| 191 | | Purpose | Declares subagent dependencies available to this agent | |
| 192 | | Format | Array of agent names. Use `*` to allow all agents, or `[]` to prevent subagent use | |
| 193 | | Requirement | When specified, include the `agent` tool in the `tools` property | |
| 194 | |
| 195 | **`model`** (string or array of strings) |
| 196 | |
| 197 | | Attribute | Details | |
| 198 | |-----------|----------------------------------------------------------------------------------------------| |
| 199 | | Purpose | Specifies the AI model for this agent | |
| 200 | | Format | Single model name or prioritized list of models (system tries each in order until available) | |
| 201 | | Default | Currently selected model in model picker when omitted | |
| 202 | |
| 203 | **`user-invocable`** (boolean) |
| 204 | |
| 205 | | Attribute | Details | |
| 206 | |-----------|-----------------------------------------------------------------| |
| 207 | | Purpose | Controls whether the agent appears in the agents dropdown | |
| 208 | | Default | `true` | |
| 209 | | Usage | Set to `false` for agents that are only accessible as subagents | |
| 210 | |
| 211 | **`disable-model-invocation`** (boolean) |
| 212 | |
| 213 | | Attribute | Details | |
| 214 | |-----------|---------------------------------------------------------------------------------------------------------------| |
| 215 | | Purpose | Prevents the agent from being invoked as a subagent by other agents | |
| 216 | | Default | `false` | |
| 217 | | Usage | Set to `true` for agents that run subagents, cause side effects, or should only run when explicitly requested | |
| 218 | |
| 219 | **`argument-hint`** (string) |
| 220 | |
| 221 | | Attribute | Details | |
| 222 | |-----------|---------------------------------------------------------| |
| 223 | | Purpose | Hint text shown in the chat input field to guide users | |
| 224 | | Format | Brief text with required arguments first, then optional | |
| 225 | |
| 226 | **`target`** (string enum) |
| 227 | |
| 228 | | Attribute | Details | |
| 229 | |--------------|-----------------------------------------| |
| 230 | | Purpose | Target environment for the custom agent | |
| 231 | | Valid values | `vscode`, `github-copilot` | |
| 232 | |
| 233 | **`mcp-servers`** (array of objects) |
| 234 | |
| 235 | | Attribute | Details | |
| 236 | |-----------|----------------------------------------------------| |
| 237 | | Purpose | MCP server configuration for GitHub Copilot agents | |
| 238 | | Usage | Only applicable when `target: github-copilot` | |
| 239 | |
| 240 | **`handoffs`** (array of objects) |
| 241 | |
| 242 | | Attribute | Details | |
| 243 | |--------------|--------------------------------------------------------------------| |
| 244 | | Purpose | Declares agent-to-agent handoff buttons that appear in the chat UI | |
| 245 | | Format | Array of handoff declarations | |
| 246 | | Requirements | VS Code 1.106+ required for handoff support | |
| 247 | |
| 248 | Fields per handoff: |
| 249 | |
| 250 | * `label` (string, required): Button text displayed in UI, supports emoji |
| 251 | * `agent` (string, required): Target agent filename without `.agent.md` extension |
| 252 | * `prompt` (string, optional): Pre-filled prompt text, can include slash commands |
| 253 | * `send` (boolean, optional): When true, auto-submits prompt; when false (default), user can edit |
| 254 | * `model` (string, optional): Language model override for the handoff execution |
| 255 | |
| 256 | Example: |
| 257 | |
| 258 | ```yaml |
| 259 | handoffs: |
| 260 | - label: "📋 Create Plan" |
| 261 | agent: Task Planner |
| 262 | prompt: /task-plan |
| 263 | send: true |
| 264 | ``` |
| 265 | |
| 266 | ### Deprecated Fields |
| 267 | |
| 268 | **`infer`** (boolean) |
| 269 | |
| 270 | | Attribute | Details | |
| 271 | |-------------------|---------------------------------------------------------------------------------------------------------------------------------| |
| 272 | | Status | Deprecated. Use `user-invocable` and `disable-model-invocation` instead. | |
| 273 | | Previous behavior | `infer: true` (default) made the agent both visible in the picker and available as a subagent. `infer: false` hid it from both. | |
| 274 | |
| 275 | ### Frontmatter Example |
| 276 | |
| 277 | ```yaml |
| 278 | --- |
| 279 | description: 'Validates and reviews contributed agents, prompts, and instructions for quality and compliance' |
| 280 | tools: ['codebase', 'search', 'problems', 'editFiles', 'changes', 'usages'] |
| 281 | disable-model-invocation: true |
| 282 | agents: |
| 283 | - Prompt Tester |
| 284 | - Prompt Evaluator |
| 285 | --- |
| 286 | ``` |
| 287 | |
| 288 | ## Collection Entry Requirements |
| 289 | |
| 290 | All agents must have matching entries in one or more `collections/*.collection.yml` manifests. Collection entries control selection and maturity. |
| 291 | |
| 292 | ### Adding Your Agent to a Collection |
| 293 | |
| 294 | After creating your agent file, add an `items[]` entry to each target collection: |
| 295 | |
| 296 | ```yaml |
| 297 | items: |
| 298 | # path can reference artifacts from any subfolder |
| 299 | - path: .github/agents/{collection-id}/my-new-agent.agent.md |
| 300 | kind: agent |
| 301 | maturity: stable |
| 302 | ``` |
| 303 | |
| 304 | ### Selecting Collections for Agents |
| 305 | |
| 306 | Choose collections based on who benefits most from your agent: |
| 307 | |
| 308 | | Agent Type | Recommended Collections | |
| 309 | |------------------------|-------------------------------------------| |
| 310 | | Task workflow agents | `hve-core-all`, `hve-core` | |
| 311 | | Architecture agents | `hve-core-all`, `project-planning` | |
| 312 | | Documentation agents | `hve-core-all`, `hve-core` | |
| 313 | | Data science agents | `hve-core-all`, `data-science` | |
| 314 | | Design thinking agents | `hve-core-all`, `design-thinking` | |
| 315 | | ADO/work item agents | `hve-core-all`, `ado`, `project-planning` | |
| 316 | | Code review agents | `hve-core-all`, `hve-core` | |
| 317 | |
| 318 | ### Declaring Agent Dependencies |
| 319 | |
| 320 | 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. |
| 321 | |
| 322 | For complete collection documentation, see [AI Artifacts Common Standards - Collection Manifests](ai-artifacts-common.md#collection-manifests). |
| 323 | |
| 324 | ### MCP Tool Dependencies |
| 325 | |
| 326 | When agents reference MCP tools in their `tools:` frontmatter or body content, document the dependencies clearly. |
| 327 | |
| 328 | **Frontmatter declaration:** |
| 329 | |
| 330 | ```yaml |
| 331 | tools: ['github/*', 'ado/*', 'context7/*', 'microsoft-docs/*'] |
| 332 | ``` |
| 333 | |
| 334 | **Curated MCP servers referenced by HVE-Core agents:** |
| 335 | |
| 336 | | Server | Tool Pattern | Purpose | |
| 337 | |----------------|--------------------|-------------------------------------------| |
| 338 | | github | `github/*` | GitHub repository and issue management | |
| 339 | | ado | `ado/*` | Azure DevOps work items, pipelines, repos | |
| 340 | | context7 | `context7/*` | Library and SDK documentation lookup | |
| 341 | | microsoft-docs | `microsoft-docs/*` | Microsoft Learn documentation | |
| 342 | |
| 343 | **Guidelines for MCP tool references:** |
| 344 | |
| 345 | * Document MCP dependencies in agent body text when using `mcp_*` tool patterns |
| 346 | * Agents should gracefully handle missing MCP servers (tools unavailable) |
| 347 | * Reference the [MCP Server Configuration](../getting-started/mcp-configuration.md) guide when agents require MCP tools |
| 348 | * Prefer built-in VS Code Copilot tools when equivalent functionality exists |
| 349 | |
| 350 | ## Agent Content Structure Standards |
| 351 | |
| 352 | ### Required Sections |
| 353 | |
| 354 | #### 1. Title (H1) |
| 355 | |
| 356 | * Clear, action-oriented heading matching agent purpose |
| 357 | * Should align with filename and description |
| 358 | |
| 359 | ```markdown |
| 360 | # Content Validator Agent |
| 361 | ``` |
| 362 | |
| 363 | #### 2. Overview/Role Definition |
| 364 | |
| 365 | * Explains what the agent does and when to use it |
| 366 | * Defines scope and boundaries |
| 367 | * Sets expectations for users |
| 368 | |
| 369 | ```markdown |
| 370 | You are an expert reviewer for GitHub Copilot agents, prompts, and instruction files. |
| 371 | Your mission is to ensure all contributed guidance files meet hve-core quality standards |
| 372 | before they're merged into the library. |
| 373 | ``` |
| 374 | |
| 375 | #### 3. Core Directives/Instructions |
| 376 | |
| 377 | * Uses clear, imperative language |
| 378 | * Employs RFC 2119 keywords consistently: |
| 379 | * **MUST/WILL/MANDATORY/CRITICAL** - Required behavior |
| 380 | * **SHOULD/RECOMMENDED** - Strong guidance |
| 381 | * **MAY/OPTIONAL** - Permitted but not required |
| 382 | * Provides step-by-step workflows |
| 383 | * Includes decision points and branching logic |
| 384 | |
| 385 | #### 4. Examples and Templates |
| 386 | |
| 387 | * Demonstrates correct usage patterns |
| 388 | * Shows both positive (✅) and negative (❌) examples |
| 389 | * Wraps in XML-style blocks for reusability |
| 390 | |
| 391 | #### 5. Success Criteria |
| 392 | |
| 393 | * Defines completion conditions |
| 394 | * Specifies validation checkpoints |
| 395 | * Lists quality gates |
| 396 | |
| 397 | #### 6. Attribution Footer |
| 398 | |
| 399 | Include at end of file (MANDATORY): |
| 400 | |
| 401 | ```markdown |
| 402 | --- |
| 403 | |
| 404 | Brought to you by microsoft/hve-core |
| 405 | ``` |
| 406 | |
| 407 | ### XML-Style Block Requirements |
| 408 | |
| 409 | See [AI Artifacts Common Standards - XML-Style Block Standards](ai-artifacts-common.md#xml-style-block-standards) for complete rules and examples. |
| 410 | |
| 411 | ### Directive Language Standards |
| 412 | |
| 413 | 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. |
| 414 | |
| 415 | ## Tool Usage Discipline |
| 416 | |
| 417 | When agents use tools, they **MUST** follow these patterns: |
| 418 | |
| 419 | ### Tool Usage Preambles |
| 420 | |
| 421 | Before any batch of tool calls, include a one-sentence explanation: |
| 422 | |
| 423 | ```markdown |
| 424 | **Tool Usage Preamble**: "Analyzing file structure, reading schemas, and checking |
| 425 | repository conventions to establish validation baseline." |
| 426 | ``` |
| 427 | |
| 428 | ### Checkpoints |
| 429 | |
| 430 | After 3-5 tool calls or more than 3 file edits, provide a compact checkpoint: |
| 431 | |
| 432 | ```markdown |
| 433 | **Checkpoint After Discovery**: "Identified [file type], loaded [schema name], |
| 434 | found [N] related files for comparison." |
| 435 | ``` |
| 436 | |
| 437 | ### Tool Result Integration |
| 438 | |
| 439 | * Document how tool results inform next steps |
| 440 | * Specify error handling for tool failures |
| 441 | * Justify tool selection (why this tool for this task) |
| 442 | |
| 443 | ## Output Formatting Requirements |
| 444 | |
| 445 | Define how the agent communicates with users: |
| 446 | |
| 447 | ### Response Format |
| 448 | |
| 449 | * Start all responses with: `## **[Agent Name]**: [Action Description]` |
| 450 | * Use short, action-oriented section headers |
| 451 | * Employ proper markdown formatting |
| 452 | * Include emojis for visual clarity (when appropriate) |
| 453 | |
| 454 | ### Status Reporting |
| 455 | |
| 456 | Specify formats for: |
| 457 | |
| 458 | * Progress updates |
| 459 | * Error messages |
| 460 | * Completion confirmations |
| 461 | * Validation results |
| 462 | |
| 463 | ### Requirements Checklist |
| 464 | |
| 465 | For agents performing edits or validations: |
| 466 | |
| 467 | ```markdown |
| 468 | ### Requirements Checklist |
| 469 | |
| 470 | - [x] Pre-validation analysis complete - Loaded schema, checked conventions |
| 471 | - [x] Frontmatter validation - All required fields present |
| 472 | - [ ] Technical validation - 2 broken file references found |
| 473 | ``` |
| 474 | |
| 475 | ### Quality Gates |
| 476 | |
| 477 | Report validation status: |
| 478 | |
| 479 | ```markdown |
| 480 | ### Quality Gates |
| 481 | |
| 482 | - **Build**: PASS |
| 483 | - **Lint**: FAIL - Markdownlint flagged: bare URLs (lines 45, 67) |
| 484 | - **Schema**: PASS - Frontmatter validates |
| 485 | ``` |
| 486 | |
| 487 | ## Research and External Sources |
| 488 | |
| 489 | 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. |
| 490 | |
| 491 | ## Validation Checklist |
| 492 | |
| 493 | Before submitting your agent, verify: |
| 494 | |
| 495 | ### Frontmatter |
| 496 | |
| 497 | * [ ] Valid YAML between `---` delimiters |
| 498 | * [ ] `description` field present and descriptive (10-200 chars) |
| 499 | * [ ] `tools` array contains only valid tool names (if present) |
| 500 | * [ ] `agents` array contains valid subagent names (if present) |
| 501 | * [ ] `user-invocable` and `disable-model-invocation` used correctly (if present) |
| 502 | * [ ] No trailing whitespace in values |
| 503 | * [ ] Single newline at EOF |
| 504 | |
| 505 | ### Content Structure |
| 506 | |
| 507 | * [ ] Clear H1 title matching purpose |
| 508 | * [ ] Overview/role definition section |
| 509 | * [ ] Core directives with RFC 2119 keywords |
| 510 | * [ ] Examples wrapped in XML-style blocks |
| 511 | * [ ] Success criteria defined |
| 512 | * [ ] Attribution footer present |
| 513 | |
| 514 | ### Common Standards |
| 515 | |
| 516 | * [ ] Markdown quality (see [Common Standards - Markdown Quality](ai-artifacts-common.md#markdown-quality-standards)) |
| 517 | * [ ] XML-style blocks properly formatted (see [Common Standards - XML-Style Blocks](ai-artifacts-common.md#xml-style-block-standards)) |
| 518 | * [ ] RFC 2119 keywords used consistently (see [Common Standards - RFC 2119](ai-artifacts-common.md#rfc-2119-directive-language)) |
| 519 | |
| 520 | ### Technical Validation |
| 521 | |
| 522 | * [ ] All file references point to existing files |
| 523 | * [ ] External links are valid and accessible |
| 524 | * [ ] Tool names in frontmatter are correct |
| 525 | * [ ] No conflicts with existing agents |
| 526 | |
| 527 | ### Integration |
| 528 | |
| 529 | * [ ] Aligns with `.github/copilot-instructions.md` |
| 530 | * [ ] Follows repository conventions |
| 531 | * [ ] Compatible with existing workflows |
| 532 | * [ ] Does not duplicate existing agent functionality |
| 533 | |
| 534 | ## Testing Your Agent |
| 535 | |
| 536 | See [AI Artifacts Common Standards - Common Testing Practices](ai-artifacts-common.md#common-testing-practices) for testing guidelines. For agents specifically: |
| 537 | |
| 538 | 1. Test with realistic scenarios matching the agent's purpose |
| 539 | 2. Verify tool usage patterns execute correctly |
| 540 | 3. Ensure decision points and branching logic work as intended |
| 541 | 4. Check edge cases: missing data, invalid inputs, tool failures |
| 542 | |
| 543 | ## Common Issues and Fixes |
| 544 | |
| 545 | ### Agent-Specific Issues |
| 546 | |
| 547 | ### Invalid Tool Names |
| 548 | |
| 549 | Referencing tools that don't exist or using incorrect camelCase variants. Use exact tool names from VS Code Copilot's available tools list. |
| 550 | |
| 551 | 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). |
| 552 | |
| 553 | ## Automated Validation |
| 554 | |
| 555 | Run these commands before submission (see [Common Standards - Common Validation](ai-artifacts-common.md#common-validation-standards)): |
| 556 | |
| 557 | * `npm run lint:frontmatter` |
| 558 | * `npm run lint:md` |
| 559 | * `npm run spell-check` |
| 560 | * `npm run lint:md-links` |
| 561 | |
| 562 | All checks **MUST** pass before merge. |
| 563 | |
| 564 | ## Related Documentation |
| 565 | |
| 566 | * [AI Artifacts Common Standards](ai-artifacts-common.md) - Shared standards for all contributions |
| 567 | * [Contributing Prompts](prompts.md) - Workflow-specific guidance files |
| 568 | * [Contributing Instructions](instructions.md) - Technology-specific standards |
| 569 | * [Pull Request Template](../../.github/PULL_REQUEST_TEMPLATE.md) - Submission requirements |
| 570 | |
| 571 | ## Getting Help |
| 572 | |
| 573 | 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/{collection-id}/` (the conventional location for agent files). |
| 574 | |
| 575 | --- |
| 576 | |
| 577 | <!-- markdownlint-disable MD036 --> |
| 578 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 579 | then carefully refined by our team of discerning human reviewers.* |
| 580 | <!-- markdownlint-enable MD036 --> |