Skip to main content

In this article

Contributing Prompts to HVE Core

This guide defines the requirements, standards, and best practices for contributing GitHub Copilot prompt files (.prompt.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 a Prompt?​

A prompt is a workflow-specific guidance document that provides context, requirements, and step-by-step instructions for GitHub Copilot to complete a particular task or process. Prompts are typically invoked in specific contexts or workflows.

Use Cases for Prompts​

Create a prompt when you need to:

  • Guide a specific workflow or process (e.g., creating pull requests, processing work items)
  • Provide context-sensitive instructions triggered by user actions
  • Define a repeatable task with clear inputs and outputs
  • Document a multi-step procedure for AI execution
  • Establish standards for a particular type of deliverable

File Structure Requirements​

Location​

Prompt files are typically organized in a package subdirectory by convention:

.github/prompts/{package-id}/
└── your-prompt-name.prompt.md

NOTE

Marketplace package recipes can reference artifacts from any canonical subfolder. Standard component paths are declared in .github/plugin/marketplace.json and resolve to canonical source files.

Naming Convention​

  • Use lowercase kebab-case: pull-request.prompt.md
  • Be specific about workflow/task: ado-create-pull-request.prompt.md
  • Include domain prefix when relevant: ado-, git-, github-
  • Avoid generic names: workflow.prompt.md ❌ → security-plan-from-prd.prompt.md ✅

File Format​

Prompt files MUST:

  1. Use the .prompt.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)

PropertyValue
PurposeConcise explanation of prompt purpose and use case
FormatSingle sentence, 10-200 characters
StyleSentence case with proper punctuation
Example'Required protocol for creating Azure DevOps pull requests with work item discovery and reviewer identification'

Optional Fields​

agent (string)

PropertyValue
PurposeDelegates execution to a named custom agent
FormatHuman-readable agent name matching the agent's name: frontmatter field
StyleQuote the value when the agent name contains spaces
Example'ADO Backlog Manager'

argument-hint (string)

PropertyValue
PurposeDisplays expected inputs in the VS Code prompt picker
FormatBrief string; required arguments first, then optional; [] for positional, key=value for named, {option1|option2} for enumerated choices
StyleKeep hints concise; lead with required arguments
Example"project=... [type={Epic|Feature|UserStory|Bug|Task}] [title=...]"

model (string or array of strings)

PropertyValue
PurposeSpecifies a preferred AI model for prompt invocation (cost optimization)
FormatModel display name with (copilot) suffix, or prioritized array for fallback
StyleUse names from scripts/linting/model-catalog.json; omit if the session default is acceptable
ExampleClaude Haiku 4.5 (copilot)

Use model on prompts that perform mechanical operations (git commits, issue creation, file I/O) rather than complex reasoning or code generation.

The model property is a preference hint, not a hard requirement. When the specified model is unavailable or exceeds the user's session model cost tier, VS Code falls back through the array (if specified) then to the session model. A single-model string is safe: it never causes failure. Fallback arrays add resilience when cost-tier constraints may make the primary model unavailable.

Run npm run lint:models to validate model references against the catalog.

disable-model-invocation (boolean)

PropertyValue
PurposePrevents the prompt from automatically invoking an AI model at start
FormatBoolean (true or false)
StyleUse for prompts that gather context or run setup steps before handing off to the user
Exampletrue

mode (string)

PropertyValue
PurposeSpecifies the invocation context
FormatEnumerated string; valid values: agent, assistant, copilot, workflow
StyleLowercase
Exampleagent

category (string)

PropertyValue
PurposeGroups the prompt by topic or domain for organizational purposes
FormatString identifying the domain or topic area
StyleLowercase kebab-case (e.g., code-review, ado, git)
Examplecode-review

version (string)

PropertyValue
PurposeTracks prompt revisions
FormatSemantic versioning string (MAJOR.MINOR.PATCH)
StyleQuoted string
Example'1.0.0'

author (string)

PropertyValue
PurposeAttribution for the prompt creator
FormatTeam or repository identifier string
StyleUse org/repo format or a team name
Example'microsoft/hve-core'

lastUpdated (string)

PropertyValue
PurposeTimestamp of last modification
FormatISO 8601 date string (YYYY-MM-DD)
StyleQuoted string
Example'2026-03-17'

Frontmatter Example​

---
description: 'Required protocol for creating Azure DevOps pull requests with work item discovery, reviewer identification, and automated linking'
agent: 'ADO Backlog Manager'
argument-hint: "project-slug=... [type={PR|Draft}]"
version: '1.0.0'
author: 'microsoft/hve-core'
lastUpdated: '2026-03-17'
---

Input Variables​

Prompts can declare input variables that VS Code resolves at invocation time. The syntax is:

${input:varName}
${input:varName:defaultValue}

Declare variables in an Inputs section and reference them in prompt content:

## Inputs

* ${input:topic}: (Required) Primary topic or focus area.
* ${input:scope:all}: (Optional, defaults to all) Scope of the operation.

Required inputs (no default) are inferred from the user's conversation or attached files when not explicitly supplied.

Activation Lines​

Prompts that need to clarify the workflow entry point can include an activation line: a --- separator followed by an instruction that tells the agent where to begin. Activation lines apply only to prompt files and are omitted when the delegated agent's phases already define the workflow start.

---

Begin by reading the current branch state and identifying open work items.

Prompts that delegate to a custom agent via agent: typically omit the activation line because the agent's phases define execution order.

Marketplace Recipe Registration​

Distributable prompts must be declared under the commands field of the hve-core entry in .github/plugin/marketplace.json. Use the .github-root-relative canonical path prompts/<subpath>/<name>.prompt.md.

Add non-stable lifecycle disclosure only through x-hve.componentMaturity, update docs/plugins/hve-core.md, then run npm run lint:marketplace and npm run docs:generate:check.

Prompt Content Structure Standards​

Required Sections​

1. Title (H1)​

  • Clear, action-oriented heading describing the workflow
  • Should align with filename and description
# Azure DevOps Pull Request Creation Protocol

2. Overview/Purpose​

  • Explains what the prompt does and when to use it
  • Defines scope and prerequisites
  • Lists expected outcomes
## Overview

This prompt guides the creation of Azure DevOps pull requests with automated
work item discovery, reviewer identification, and compliance validation.

3. Prerequisites/Context​

  • Lists required information, tools, or setup
  • Specifies environment assumptions
  • Defines input requirements
## Prerequisites

* Active Azure DevOps connection
* Current branch with committed changes
* Work item IDs or branch naming following conventions

4. Workflow Steps​

  • Provides clear, numbered steps for execution
  • Uses imperative, unambiguous language
  • Includes decision points and branching logic
  • Specifies tool usage at each step
## Workflow Steps

1. Discovery Phase: Identify related work items from branch name or commit messages
2. Reviewer Selection: Query ADO for default reviewers based on repository policies
3. PR Creation: Generate PR with title, description, and work item links
4. Validation: Verify PR was created successfully with correct metadata

5. Success Criteria​

  • Defines completion conditions
  • Specifies validation checkpoints
  • Lists expected artifacts
## Success Criteria

* [ ] PR created in target repository
* [ ] Work items linked to PR
* [ ] Required reviewers added
* [ ] PR description follows template

6. Examples​

  • Demonstrates correct usage with realistic scenarios
  • Shows input/output patterns
  • Wraps in XML-style blocks for reusability

7. Error Handling​

  • Documents common failure modes
  • Provides recovery procedures
  • Specifies fallback behaviors

Source artifacts carry no attribution footer.

XML-Style Block Requirements​

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

Template Variable Standards​

Use {{double_curly_braces}} for placeholders:

# ✅ CORRECT: Template variables in YAML frontmatter
---
title: "{{feature_name}} - {{brief_description}}"
branch: "feature/{{work_item_id}}-{{task_name}}"
assignee: "{{user_email}}"
---

# ❌ INCORRECT: Non-standard variable syntax in YAML frontmatter
---
title: "<feature-name> - <brief-description>"
branch: "feature/<work-item-id>-<task-name>"
assignee: "<user.email>"
---

Variable Naming​

  • Use snake_case: {{work_item_id}}, {{user_name}}
  • Be descriptive: {{target_branch}} not {{tb}}
  • Group related variables: {{pr_title}}, {{pr_description}}, {{pr_labels}}

Directive Language Standards​

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

Workflow Definition Standards​

Prompts should clearly define:

Entry Points​

What triggers this prompt:

## Invocation

This prompt is invoked when:

* User requests "create ADO pull request"
* User runs command: `/prompt ado-create-pull-request`
* Workflow automation reaches PR creation step

Decision Points​

Where choices affect flow:

## Decision Logic

**If** work items found in branch name:
  → Use those work items for linking

**Else if** work items in commit messages:
  → Extract and use those work items

Else:
  → Prompt user for work item IDs

Tool Usage​

Which tools are used and when:

## Required Tools

1. `mcp_azure_devops` - Work item queries and PR creation
2. `git/*` - Branch and commit information
3. `search` - Repository policy lookups

Output Specifications​

What artifacts are produced:

## Output Artifacts

1. Pull Request: Created in ADO with metadata
2. Handoff Document: `.copilot-tracking/pr/{{YYYY-MM-DD}}-pr-{{id}}-handoff.md`
3. Validation Report: Summary of PR creation status

Context Requirements​

Prompts SHOULD specify:

File/Path Contexts​

When specific files/paths trigger behavior:

---
description: 'Required protocol for creating Azure DevOps pull requests'
applyTo: '**/.copilot-tracking/pr/new/**'  # Workflow-specific context
---

Data Requirements​

What information must be available:

## Required Context

* `{{current_branch}}` - Active git branch name
* `{{target_branch}}` - Destination branch (default: main/master)
* `{{repository_url}}` - ADO repository URL
* `{{user_email}}` - Current user's email for reviewer queries

State Assumptions​

What must be true before execution:

## Preconditions

* Working directory is a git repository
* Changes are committed to current branch
* User has ADO credentials configured
* Target branch exists in remote repository

Output Formatting Requirements​

Define how the prompt produces results:

Response Format​

Structure for user-facing output:

## Output Format

### PR Creation Summary

Status: [Success|Failed]
PR ID: [ID]
PR URL: [URL]
Work Items Linked: [IDs]
Reviewers Added: [Names]

### Validation Results

* [x] PR created successfully
* [x] Work items linked
* [ ] CI pipeline triggered

File Outputs​

Specifications for generated files:

## Handoff Document Format

File: `.copilot-tracking/pr/{{YYYY-MM-DD}}-pr-{{id}}-handoff.md`

Content:

* PR metadata (ID, URL, title)
* Work item links with status
* Reviewer assignments
* Validation checklist

Error Reporting​

Format for failure scenarios:

## Error Format

Error Type: [Authentication|Validation|Network]
Message: [Detailed error description]
Recovery Steps:

1. [Step to resolve]
2. [Alternative approach]

Validation Checklist​

Before submitting your prompt, verify:

Frontmatter​

  • Valid YAML between --- delimiters
  • description field present and descriptive (10-200 chars)
  • mode field present with valid value
  • category field appropriate for domain (if present)
  • No trailing whitespace in values
  • Single newline at EOF

Content Structure​

  • Clear H1 title describing workflow
  • Overview/purpose section
  • Maturity set in marketplace package metadata (see Common Standards - Maturity)
  • Prerequisites or context section
  • Workflow steps with clear sequence
  • Success criteria defined
  • Error handling documented
  • Attribution footer absent

Workflow Definition​

  • Entry points/triggers specified
  • Decision logic clearly documented
  • Tool usage requirements listed
  • Output artifacts defined
  • State assumptions documented

Common Standards​

Technical Validation​

  • All file references point to existing files
  • External links are valid and accessible
  • Tool references use correct names
  • Template variables are clearly defined

Integration​

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

Authoring with the HVE Builder Skill​

The hve-builder skill is the lifecycle entrypoint for prompts, instruction files, agents, subagents, and skills. It applies the standards on this page, dispatches independent review, runs behavior testing when a change warrants it, and resolves a single overall outcome. Prefer it over hand-editing when you are creating a new prompt or making a behavior-bearing change to an existing one.

Activate it by asking for the work in natural language, optionally naming the mode. There is no slash command; hve-builder is a skill, not a prompt.

Modes​

ModeWrite authorityUse when
createCreates new source artifactsThe target prompt does not exist yet
improveEdits existing sourceAn existing prompt needs new or corrected behavior
refactorEdits existing sourceCleanup must preserve current behavior
replaceRewrites existing sourceThe artifact needs wholesale replacement
reviewRead-only; writes evidenceYou want static and behavior findings without source changes
validateRead-only; writes evidenceYou want host validation results only

The skill infers the narrowest safe mode when you do not name one, and asks only when plausible modes would grant materially different write authority.

Compatibility aliases​

Three alias skills preserve legacy activation phrasing and route straight to hve-builder. They add no second author, test, or evaluation loop.

Alias skillRoutes to
prompt-builderhve-builder in create or improve
prompt-analyzehve-builder in read-only review
prompt-refactorhve-builder in refactor

Each alias translates its legacy promptFiles input to the hve-builder targets input. New work should name hve-builder and its mode directly.

Behavior testing​

hve-builder delegates behavior testing to hve-builder-tester, which is the sole behavior-testing entrypoint. Behavior testing runs for major mutations and for behavior-bearing review targets, and is legitimately skipped for eligible minor and medium changes.

Evidence​

Runs write author, review, behavior-test, and validation evidence under .copilot-tracking/hve-builder/{{YYYY-MM-DD}}/ unless you supply a different evidence root. Read-only modes change nothing else.

Authoring standards for all artifact kinds live in .github/instructions/hve-core/hve-builder.instructions.md.

Testing Your Prompt​

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

  1. Follow prompt steps manually to verify workflow logic
  2. Test with AI execution using realistic scenarios
  3. Verify all output artifacts match specifications
  4. Test decision points with different data conditions

Common Issues and Fixes​

Prompt-Specific Issues​

Template Variables with Wrong Format​

Using incorrect syntax for template variables (angle brackets or shell-style) causes failures. Always use {{variable_name}} handlebars format for template variables.

Ambiguous Workflow Steps​

Vague workflow steps without specific tools, conditions, or decision logic cause confusion. Provide explicit tool usage, decision trees, and fallback strategies with clear conditional logic.

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
  • npm run docs:generate (required when adding a new prompt; scaffolds the reference page under docs/reference/prompts/)
  • npm run lint:asset-docs

All checks MUST pass before merge.

Getting Help​

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

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