# How Prompts Differ from Agents in HVE Core: The Complete Artifact Type Guide

> Discover how prompts differ from agents in HVE Core. Learn about lightweight prompts for user intent and stateful agents for multi-step workflows in this artifact type guide.

- Repository: [Microsoft/hve-core](https://github.com/microsoft/hve-core)
- Tags: deep-dive
- Published: 2026-03-09

---

**In microsoft/hve-core, prompts are lightweight entry-point files that capture user intent and declare target agents via front-matter, while agents are stateful orchestrators that execute multi-step workflows, manage sub-agents through `handoffs:`, and enforce validation logic.**

The microsoft/hve-core repository implements a four-tier artifact system that separates user interaction from complex workflow orchestration. Understanding how prompts differ from agents is critical for building maintainable AI-driven automations, as these distinct artifact types define the boundary between *what* a user wants to accomplish and *how* the system executes that request.

## Core Responsibilities: Entry Points vs. Orchestrators

The primary architectural distinction lies in scope and persistence. **Prompts** (`*.prompt.md`) function as disposable entry points that translate natural language requests into structured delegations. They exist only for the initial invocation, capture inputs through placeholders like `${input:...}`, and immediately route to their designated agent via the `agent:` front-matter field.

**Agents** (`*.agent.md`) persist across multiple execution steps and maintain conversation state. According to the architecture documentation in [`docs/architecture/ai-artifacts.md`](https://github.com/microsoft/hve-core/blob/main/docs/architecture/ai-artifacts.md), agents act as "task-specific behaviors" that coordinate sub-agents, invoke skills, and validate outputs before handing off to the next workflow stage.

### Scope of Responsibility

*   **Prompts** answer: *What does the user want to accomplish?*
*   **Agents** answer: *How should this task be executed?*

This separation keeps the user-facing surface simple while allowing complex, reusable orchestration logic to live within agents. A single agent like `Task Planner` can service multiple prompts ([`task-plan.prompt.md`](https://github.com/microsoft/hve-core/blob/main/task-plan.prompt.md), [`task-research.prompt.md`](https://github.com/microsoft/hve-core/blob/main/task-research.prompt.md)) without duplicating workflow logic.

## Anatomy of a Prompt Artifact

Prompt files reside in `.github/prompts/hve-core/` and contain minimal front-matter that declares the target agent and expected inputs.

```yaml
--- 
description: "Initiates implementation planning based on user context or research documents"
agent: Task Planner
argument-hint: "[research=...] [chat={true|false}]"
---

# Task Plan

## Inputs

* ${input:chat:true}: (Optional) Include conversation context.
* ${input:research}: (Optional) Path to a research file.

```

Key characteristics of the prompt structure in [`.github/prompts/hve-core/task-plan.prompt.md`](https://github.com/microsoft/hve-core/blob/main/.github/prompts/hve-core/task-plan.prompt.md):

*   The **`agent:`** field specifies which orchestrator receives the request.
*   **`${input:...}`** placeholders define required and optional parameters with default values.
*   Prompts are **single-session** artifacts; they accept inputs, delegate to their agent, then return control to the user.

## Anatomy of an Agent Artifact

Agent files reside in `.github/agents/hve-core/` and contain rich configuration for multi-step execution, including sub-agent lists and handoff policies.

```yaml
--- 
name: Task Planner
description: "Implementation planner for creating actionable implementation plans"
disable-model-invocation: true
agents:
  - Researcher Subagent
  - Plan Validator
handoffs:
  - label: "⚡ Implement"
    agent: Task Implementor
    prompt: /task-implement
    send: true
---

# Task Planner

Create actionable implementation plans. Produce two files per task: implementation plan and implementation details.

```

Key characteristics of the agent structure in [`.github/agents/hve-core/task-planner.agent.md`](https://github.com/microsoft/hve-core/blob/main/.github/agents/hve-core/task-planner.agent.md):

*   **`agents:`** lists sub-agents (e.g., `Researcher Subagent`, `Plan Validator`) that this orchestrator can invoke.
*   **`handoffs:`** defines state transitions to other agents or prompts, enabling complex workflow pipelines.
*   Agents maintain **state** across multiple steps and can enforce validation before proceeding.

## The Delegation Chain: How Prompts and Agents Interact

The interaction model follows a strict hierarchy defined in [`docs/architecture/ai-artifacts.md`](https://github.com/microsoft/hve-core/blob/main/docs/architecture/ai-artifacts.md). When a user invokes `/prompt task-plan`, the system:

1.  Loads the prompt file and parses the **`agent:`** front-matter reference.
2.  Binds input parameters to the `${input:...}` placeholders.
3.  Transfers control to the specified agent (e.g., `Task Planner`).
4.  The agent orchestrates sub-agents listed in its **`agents:`** array.
5.  Upon completion, the agent executes **`handoffs:`** to route results to the next stage (e.g., `Task Implementor`).

This flow demonstrates why prompts remain lightweight—they capture intent and route, while agents handle the heavy lifting of coordination, validation, and state management.

## Summary

*   **Prompts** (`*.prompt.md`) are entry-point files in `.github/prompts/` that declare an `agent:` target and define input placeholders; they are stateless and invoked directly by users.
*   **Agents** (`*.agent.md`) are orchestration files in `.github/agents/` that configure `agents:`, `tools:`, and `handoffs:` to manage multi-step workflows and maintain execution state.
*   **Reusability**: Multiple prompts can route to a single agent, and agents can be composed of reusable sub-agents without code duplication.
*   **Extensibility**: New workflows often require only new prompt files pointing to existing agents, minimizing changes to core orchestration logic.

## Frequently Asked Questions

### Can a prompt invoke multiple agents directly?

No, a prompt delegates to exactly one agent specified in its `agent:` front-matter field. If multi-agent coordination is required, the designated agent should handle sub-agent invocation through its `agents:` list and `handoffs:` configuration.

### How do I pass data from a prompt to an agent in HVE Core?

Data flows through **`${input:...}`** placeholders defined in the prompt file. When the user invokes the prompt with arguments, these values are bound to the placeholders and passed as parameters to the target agent. The agent then accesses this data within its execution context.

### What is the difference between an agent and a skill in the artifact hierarchy?

**Agents** (`*.agent.md`) are orchestrators that manage workflows and delegate to other agents or skills. **Skills** are executable utilities (typically scripts like `.sh` or `.ps1` with a [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md) entry point) that perform concrete, atomic actions. Agents invoke skills via their `tools:` list when specific technical operations are required.

### Where should I place custom prompt files in my repository?

Custom prompts belong in `.github/prompts/hve-core/` with the `*.prompt.md` extension. The HVE Core extension automatically discovers files in this directory and makes them available for invocation via the `/prompt` command or UI shortcuts.