Contributing Agents to HVE Core

This guide defines the requirements, standards, and best practices for contributing GitHub Copilot agent files (.agent.md) to the hve-core library.

⚙️ Common Standards: See AI Artifacts Common Standards for shared requirements (XML blocks, markdown quality, RFC 2119, validation, testing).

What is an Agent?

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.

Use Cases for Agents

Create an agent when you need to:

• Define a specialized AI agent role (e.g., security reviewer, PR analyzer, documentation generator)
• Orchestrate multi-step workflows requiring specific tool sequences
• Maintain consistent behavior patterns across development tasks
• Provide domain-specific expertise (e.g., ADR creation, work item processing)
• Automate complex decision-making with predefined logic flows

Agents Not Accepted

The following agent types will likely be rejected or closed automatically because equivalent agents already exist in hve-core:

Duplicate Agent Categories

Research or Discovery Agents

Agents that search for, gather, or discover information.

• ❌ Reason: Existing agents already handle research and discovery workflows
• ✅ Alternative: Use existing research-focused agents in .github/agents/

Indexing or Referencing Agents

Agents that catalog, index, or create references to existing projects.

• ❌ Reason: Existing agents already provide indexing and referencing capabilities
• ❌ 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
• ✅ Alternative: Use existing reference management agents that use standard VS Code GitHub Copilot tools and widely-adopted MCP tools

Planning Agents

Agents that plan work, break down tasks, or organize backlog items.

• ❌ Reason: Existing agents already handle work planning and task organization
• ✅ Alternative: Use existing planning-focused agents in .github/agents/

Implementation Agents

General-purpose coding agents that implement features.

• ❌ Reason: Existing agents already provide implementation guidance
• ✅ Alternative: Use existing implementation-focused agents

Rationale for Rejection

These agent types are rejected because:

1. Existing agents are hardened and heavily used: the hve-core library already contains production-tested agents in these categories
2. Consistency and maintenance: coalescing around existing agents reduces fragmentation and maintenance burden
3. Avoid duplication: multiple agents serving the same purpose create confusion and divergent behavior
4. Standard tooling already integrated: VS Code GitHub Copilot built-in tools and widely-adopted MCP tools are already used by existing agents

Before Submitting

When planning to submit an agent that falls into these categories:

1. Question necessity: does your use case truly require a new agent, or can existing agents meet your needs?
2. Review existing agents: examine .github/agents/ to identify agents that already serve your purpose
3. Check tool integration: verify whether the VS Code GitHub Copilot tools or MCP tools you need are already used by existing agents
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
5. Propose enhancements: submit a PR to enhance an existing agent rather than creating a duplicate

What Makes a Good New Agent

Focus on agents that:

Criterion	Description
Fill gaps	Address use cases not covered by existing agents
Provide unique value	Offer specialized domain expertise or workflow patterns not present in the library
Are non-overlapping	Have clearly distinct purposes from existing agents
Cannot be merged	Represent functionality too specialized or divergent to integrate into existing agents
Use standard tooling	Use widely-supported VS Code GitHub Copilot tools and MCP tools rather than custom integrations

Model Version Requirements

All agents MUST target the latest available models from Anthropic and OpenAI only.

Accepted: Latest Claude models (e.g., Claude Sonnet 4, Claude Opus 4) and latest GPT models (e.g., GPT-5.1, o1)

Not Accepted: Older model versions (e.g., GPT-3.5, GPT-4.1, Claude 2), models from other providers, custom/fine-tuned models

Rationale: Latest models provide superior capabilities, reduce maintenance burden, and ensure future compatibility. Older model versions will be deprecated.

File Structure Requirements

Location

Agent files are typically organized in a collection subdirectory by convention:

.github/agents/{collection-id}/
├── your-agent-name.agent.md
└── subagents/
    └── your-subagent-name.agent.md

NOTE

Collections can reference artifacts from any subfolder. The path: field in collection YAML files accepts any valid repo-relative path regardless of the artifact's parent directory.

Naming Convention

• Use lowercase kebab-case: security-reviewer.agent.md
• Be descriptive and action-oriented: task-planner.agent.md, pr-review.agent.md, rpi-agent.agent.md
• Avoid generic names: helper.agent.md ❌ → ado-work-item-processor.agent.md ✅

File Format

Agent files MUST:

1. Use the .agent.md extension
2. Start with valid YAML frontmatter between --- delimiters
3. Begin content directly after frontmatter
4. End with single newline character

Frontmatter Requirements

Required Fields

description (string, MANDATORY)

Attribute	Details
Purpose	Concise explanation of agent functionality
Format	Single sentence, 10-200 characters
Style	Sentence case with proper punctuation
Example	'Validates contributed content for quality and compliance with hve-core standards'

Optional Fields

name (string)

Attribute	Details
Purpose	Custom display name for the agent
Format	Lowercase kebab-case matching filename without extension
Default	File name used if not specified

tools (array of strings)

Attribute	Details
Purpose	Lists GitHub Copilot tools available to this agent
Format	Array of valid tool names in logical order (read before write)

Valid tools:

• codebase - Semantic code search
• search - Grep/regex search
• problems - Error/warning diagnostics
• editFiles - File modification
• changes - Git change tracking
• usages - Symbol reference search
• githubRepo - External GitHub repository search
• fetch - Web page content retrieval
• runCommands - Terminal command execution
• think - Extended reasoning
• findTestFiles - Test file discovery
• terminalLastCommand - Terminal history
• searchResults - Search view results
• edit/createFile - File creation
• edit/createDirectory - Directory creation
• Bicep (EXPERIMENTAL)/* - Bicep tooling
• terraform/* - Terraform tooling
• context7/* - Library documentation
• microsoft-docs/* - Microsoft documentation

agents (array of strings)

Attribute	Details
Purpose	Declares subagent dependencies available to this agent
Format	Array of agent names. Use * to allow all agents, or [] to prevent subagent use
Requirement	When specified, include the agent tool in the tools property

model (string or array of strings)

Attribute	Details
Purpose	Specifies the AI model for this agent
Format	Single model name or prioritized list of models (system tries each in order until available)
Default	Currently selected model in model picker when omitted

user-invocable (boolean)

Attribute	Details
Purpose	Controls whether the agent appears in the agents dropdown
Default	true
Usage	Set to false for agents that are only accessible as subagents

disable-model-invocation (boolean)

Attribute	Details
Purpose	Prevents the agent from being invoked as a subagent by other agents
Default	false
Usage	Set to true for agents that run subagents, cause side effects, or should only run when explicitly requested

argument-hint (string)

Attribute	Details
Purpose	Hint text shown in the chat input field to guide users
Format	Brief text with required arguments first, then optional

target (string enum)

Attribute	Details
Purpose	Target environment for the custom agent
Valid values	vscode, github-copilot

mcp-servers (array of objects)

Attribute	Details
Purpose	MCP server configuration for GitHub Copilot agents
Usage	Only applicable when target: github-copilot

handoffs (array of objects)

Attribute	Details
Purpose	Declares agent-to-agent handoff buttons that appear in the chat UI
Format	Array of handoff declarations
Requirements	VS Code 1.106+ required for handoff support

Fields per handoff:

• label (string, required): Button text displayed in UI, supports emoji
• agent (string, required): Target agent filename without .agent.md extension
• prompt (string, optional): Pre-filled prompt text, can include slash commands
• send (boolean, optional): When true, auto-submits prompt; when false (default), user can edit
• model (string, optional): Language model override for the handoff execution

Example:

  handoffs:
    - label: "📋 Create Plan"
      agent: Task Planner
      prompt: /task-plan
      send: true

Deprecated Fields

infer (boolean)

Attribute	Details
Status	Deprecated. Use user-invocable and disable-model-invocation instead.
Previous behavior	infer: true (default) made the agent both visible in the picker and available as a subagent. infer: false hid it from both.

Frontmatter Example

---
description: 'Validates and reviews contributed agents, prompts, and instructions for quality and compliance'
tools: ['codebase', 'search', 'problems', 'editFiles', 'changes', 'usages']
disable-model-invocation: true
agents:
  - Prompt Tester
  - Prompt Evaluator
---

Collection Entry Requirements

All agents must have matching entries in one or more collections/*.collection.yml manifests. Collection entries control selection and maturity.

Adding Your Agent to a Collection

After creating your agent file, add an items[] entry to each target collection:

items:
  # path can reference artifacts from any subfolder
  - path: .github/agents/{collection-id}/my-new-agent.agent.md
  kind: agent
  maturity: stable

Selecting Collections for Agents

Choose collections based on who benefits most from your agent:

Agent Type	Recommended Collections
Task workflow agents	hve-core-all, hve-core
Architecture agents	hve-core-all, project-planning
Documentation agents	hve-core-all, hve-core
Data science agents	hve-core-all, data-science
Design thinking agents	hve-core-all, design-thinking
ADO/work item agents	hve-core-all, ado, project-planning
Code review agents	hve-core-all, hve-core

Declaring Agent Dependencies

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.

For complete collection documentation, see AI Artifacts Common Standards - Collection Manifests.

MCP Tool Dependencies

When agents reference MCP tools in their tools: frontmatter or body content, document the dependencies clearly.

Frontmatter Declaration

tools: ['github/*', 'ado/*', 'context7/*', 'microsoft-docs/*']

Curated MCP Servers Referenced by HVE-Core Agents

Server	Tool Pattern	Purpose
github	github/*	GitHub repository and issue management
ado	ado/*	Azure DevOps work items, pipelines, repos
context7	context7/*	Library and SDK documentation lookup
microsoft-docs	microsoft-docs/*	Microsoft Learn documentation

Guidelines for MCP Tool References

• Document MCP dependencies in agent body text when using mcp_* tool patterns
• Agents should gracefully handle missing MCP servers (tools unavailable)
• Reference the MCP Server Configuration guide when agents require MCP tools
• Prefer built-in VS Code Copilot tools when equivalent functionality exists

Agent Content Structure Standards

Required Sections

1. Title (H1)

• Clear, action-oriented heading matching agent purpose
• Should align with filename and description

# Content Validator Agent

2. Overview/Role Definition

• Explains what the agent does and when to use it
• Defines scope and boundaries
• Sets expectations for users

You are an expert reviewer for GitHub Copilot agents, prompts, and instruction files.
Your mission is to ensure all contributed guidance files meet hve-core quality standards
before they're merged into the library.

3. Core Directives/Instructions

• Uses clear, imperative language
• Employs RFC 2119 keywords consistently:
  • MUST, WILL, MANDATORY, and CRITICAL indicate required behavior
  • SHOULD and RECOMMENDED indicate strong guidance
  • MAY and OPTIONAL indicate permitted but not required behavior
• Provides step-by-step workflows
• Includes decision points and branching logic

4. Examples and Templates

• Demonstrates correct usage patterns
• Shows both positive (✅) and negative (❌) examples
• Wraps in XML-style blocks for reusability

5. Success Criteria

• Defines completion conditions
• Specifies validation checkpoints
• Lists quality gates

6. Attribution Footer

Include at end of file (MANDATORY):

---

Brought to you by microsoft/hve-core

XML-Style Block Requirements

See AI Artifacts Common Standards - XML-Style Block Standards for complete rules and examples.

Directive Language Standards

Use RFC 2119 compliant keywords (MUST/SHOULD/MAY). See AI Artifacts Common Standards - RFC 2119 Directive Language for complete guidance.

Tool Usage Discipline

When agents use tools, they MUST follow these patterns:

Tool Usage Preambles

Before any batch of tool calls, include a one-sentence explanation:

Tool Usage Preamble: "Analyzing file structure, reading schemas, and checking
repository conventions to establish validation baseline."

Checkpoints

After 3-5 tool calls or more than 3 file edits, provide a compact checkpoint:

Checkpoint After Discovery: "Identified [file type], loaded [schema name],
found [N] related files for comparison."

Tool Result Integration

• Document how tool results inform next steps
• Specify error handling for tool failures
• Justify tool selection (why this tool for this task)

Output Formatting Requirements

Define how the agent communicates with users:

Response Format

• Start all responses with: ## [Agent Name]: [Action Description]
• Use short, action-oriented section headers
• Employ proper markdown formatting
• Include emojis for visual clarity (when appropriate)

Status Reporting

Specify formats for:

• Progress updates
• Error messages
• Completion confirmations
• Validation results

Requirements Checklist

For agents performing edits or validations:

### Requirements Checklist

- [x] Pre-validation analysis complete - Loaded schema, checked conventions
- [x] Frontmatter validation - All required fields present
- [ ] Technical validation - 2 broken file references found

Quality Gates

Report validation status:

### Quality Gates

- Build: PASS
- Lint: FAIL - Markdownlint flagged: bare URLs (lines 45, 67)
- Schema: PASS - Frontmatter validates

Research and External Sources

When agents integrate external knowledge, consult authoritative sources and provide minimal, annotated snippets with reference links. See AI Artifacts Common Standards - Attribution Requirements for guidelines.

Validation Checklist

Before submitting your agent, verify:

Frontmatter

• Valid YAML between --- delimiters
• description field present and descriptive (10-200 chars)
• tools array contains only valid tool names (if present)
• agents array contains valid subagent names (if present)
• user-invocable and disable-model-invocation used correctly (if present)
• No trailing whitespace in values
• Single newline at EOF

Content Structure

• Clear H1 title matching purpose
• Overview/role definition section
• Core directives with RFC 2119 keywords
• Examples wrapped in XML-style blocks
• Success criteria defined
• Attribution footer present

Common Standards

• Markdown quality (see Common Standards - Markdown Quality)
• XML-style blocks properly formatted (see Common Standards - XML-Style Blocks)
• RFC 2119 keywords used consistently (see Common Standards - RFC 2119)

Technical Validation

• All file references point to existing files
• External links are valid and accessible
• Tool names in frontmatter are correct
• No conflicts with existing agents

Integration

• Aligns with .github/copilot-instructions.md
• Follows repository conventions
• Compatible with existing workflows
• Does not duplicate existing agent functionality

Testing Your Agent

See AI Artifacts Common Standards - Common Testing Practices for testing guidelines. For agents specifically:

1. Test with realistic scenarios matching the agent's purpose
2. Verify tool usage patterns execute correctly
3. Ensure decision points and branching logic work as intended
4. Check edge cases: missing data, invalid inputs, tool failures

Common Issues and Fixes

Agent-Specific Issues

Invalid Tool Names

Referencing tools that don't exist or using incorrect camelCase variants. Use exact tool names from VS Code Copilot's available tools list.

For additional common issues (XML blocks, markdown, directives), see AI Artifacts Common Standards - Common Issues and Fixes.

Automated Validation

Run these commands before submission (see Common Standards - Common Validation):

• npm run lint:frontmatter
• npm run lint:md
• npm run spell-check
• npm run lint:md-links

All checks MUST pass before merge.

Related Documentation

• AI Artifacts Common Standards - Shared standards for all contributions
• Contributing Prompts - Workflow-specific guidance files
• Contributing Instructions - Technology-specific standards
• Pull Request Template - Submission requirements

Getting Help

See AI Artifacts Common Standards - Getting Help for support resources. For agent-specific assistance, review existing examples in .github/agents/{collection-id}/ (the conventional location for agent files).

---

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.