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