hve-core/docs/architecture/ai-artifacts.md at main · microsoft/hve-core

title	AI Artifacts Architecture
description	Prompt, agent, and instruction delegation model for Copilot customizations
sidebar_position	2
author	Microsoft
ms.date	2026-03-10
ms.topic	concept

HVE Core provides a four-tier artifact system for customizing GitHub Copilot behavior. Each tier serves a distinct purpose in the delegation chain, enabling structured, reusable AI guidance that flows from user intent to technology-specific standards and executable utilities.

Artifact Type Hierarchy

The artifact system organizes customizations by scope and responsibility. Prompts handle user interaction, agents orchestrate workflows, instructions encode standards, and skills provide executable utilities.

Prompts

Prompts (.prompt.md) serve as workflow entry points. They capture user intent and translate requests into structured guidance for Copilot execution.

Core Characteristics

Define single-session workflows with clear inputs and outputs
Accept user inputs through ${input:varName} template syntax
Delegate to agents via agent: frontmatter references

Frontmatter Structure

---
description: 'Protocol for creating ADO pull requests'
agent: Task Planner
---

Prompts answer the question "what does the user want to accomplish?" and route execution to appropriate agents.

Agents

Agents (.agent.md) define task-specific behaviors with access to Copilot tools. They orchestrate multi-step workflows and make decisions based on context.

Core Characteristics

Specify available tools through tools: frontmatter arrays
Enable workflow handoffs via handoffs: references to other agents
Maintain conversation context across multiple interactions
Apply domain expertise through detailed behavioral instructions

Frontmatter Structure

---
description: 'Orchestrates task planning with research integration'
tools: ['codebase', 'search', 'editFiles', 'changes']
handoffs:
  - label: "⚡ Implement"
    agent: Task Implementor
    prompt: /task-implement
    send: true
  - label: "🔬 Research"
    agent: Task Researcher
    prompt: /task-research
    send: true
---

Agents answer the question "how should this task be executed?" and coordinate the necessary tools and resources.

Instructions

Instructions (.instructions.md) encode technology-specific standards and conventions. They apply automatically based on file patterns and provide consistent guidance across the codebase.

Core Characteristics

Match files through applyTo: glob patterns for automatic application
Define coding standards, naming conventions, and quality requirements
Apply to specific languages, frameworks, or file types
Stack with other instructions when multiple patterns match

Frontmatter Structure

---
description: 'Python scripting standards with type hints'
applyTo: '**/*.py, **/*.ipynb'
---

Instructions answer the question "what standards apply to this context?" and ensure consistent code quality.

Repo-Specific Instructions

Instructions placed at the root of .github/instructions/ (without a subdirectory) are scoped to the hve-core repository itself and MUST NOT be included in collection manifests. These files govern internal repository concerns (CI/CD workflows, repo-specific conventions) that are not applicable outside the repository. Root-level artifacts are intentionally excluded from artifact selection and package composition.

Important

Root-level files under .github/instructions/ (no subdirectory) are repo-specific and never distributed. Files in subdirectories like hve-core/, ado/, and shared/ are collection-scoped and distributable.

Skills

Skills (.github/skills/<name>/SKILL.md) provide executable utilities that agents invoke for specialized tasks. Unlike instructions (passive reference), skills contain actual scripts that perform operations.

Core Characteristics

Provide self-contained utility packages with documentation and scripts
Include parallel implementations for cross-platform support (.sh and .ps1)
Execute actual operations rather than providing guidance

Directory Structure (by Convention)

.github/skills/{collection-id}/<skill-name>/
├── SKILL.md           # Required entry point with frontmatter
├── scripts/
│   ├── convert.sh     # Bash implementation
│   └── convert.ps1    # PowerShell implementation
└── examples/
    └── README.md      # Usage examples

Frontmatter Structure

---
name: video-to-gif
description: 'Video-to-GIF conversion with FFmpeg optimization'
---

Required Frontmatter Fields

Field	Description
`name`	Lowercase kebab-case identifier matching directory name
`description`	Brief capability description

Maturity is tracked in collections/*.collection.yml, not in skill frontmatter. See Collection Manifests for details.

Skills answer the question "what specialized utility does this task require?" and provide executable capabilities beyond conversational guidance.

Key Distinction from Instructions

Aspect	Instructions	Skills
Nature	Passive reference	Active execution
Content	Standards and conventions	Scripts and utilities
Activation	Automatic via glob patterns	Explicit invocation
Output	Guidance for Copilot	Executed operations

Delegation Flow

The artifact system follows a hierarchical delegation model. User requests flow through prompts to agents, which apply relevant instructions during execution.

graph LR
    USER[User Request] --> PROMPT[Prompt]
    PROMPT --> AGENT[Agent]
    AGENT --> INSTR[Instructions]
    AGENT --> SKILLS[Skills]

Flow Mechanics

User invokes a prompt through /prompt commands or workflow triggers.
Prompt references an agent via agent: frontmatter, delegating execution.
Agent executes with instructions auto-applied based on file context.
Agent invokes skills for specialized utilities with executable scripts.

This delegation model separates concerns. Prompts handle user interaction, agents manage orchestration, and instructions provide standards.

Interface Contracts

Each artifact type defines clear interfaces for interoperability.

Prompt-to-Agent References

Prompts reference agents through the agent: frontmatter field:

---
description: 'Create a pull request with work item linking'
agent: 'pr-creator'
---

The referenced agent file (pr-creator.agent.md) is typically organized under .github/agents/{collection-id}/ by convention. When a user invokes the prompt, Copilot activates the specified agent with the prompt's context.

Instruction Glob Patterns

Instructions use applyTo: patterns for automatic activation:

Pattern	Matches
`*/.py`	All Python files recursively
`/tests//*.ts`	TypeScript files in test directories
`/.copilot-tracking/pr/`	PR tracking files

Multiple instructions can apply to the same file. When patterns overlap, all matching instructions contribute guidance. Pattern specificity determines precedence for conflicting directives.

Skill Entry Points

Skills provide self-contained utilities through the SKILL.md file:

.github/skills/{collection-id}/<skill-name>/
├── SKILL.md                    # Entry point documentation
├── convert.sh                  # Bash implementation
├── convert.ps1                 # PowerShell implementation
└── examples/
    └── README.md

The {collection-id} path segment reflects the conventional organization; artifacts can reside in any subfolder.

Copilot discovers skills automatically when their description matches the current task context. Skills can also be referenced explicitly by name. The skill's SKILL.md documents prerequisites, parameters, and usage patterns. Cross-platform scripts ensure consistent behavior across operating systems.

Collection Manifests

Collection manifests in collections/*.collection.yml serve as the source of truth for artifact selection and maturity. They drive packaging for extension collections and contributor workflows without adding maturity metadata to artifact frontmatter.

Collection Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                     Collection Manifests                             │
│  collections/*.collection.yml                                        │
│  ┌─────────────────────────────────────────────────────────────┐     │
│  │ items[]                                                     │     │
│  │ - path                                                      │     │
│  │ - kind                                                      │     │
│  │ - maturity (optional, defaults to stable)                  │     │
│  └─────────────────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         Build System                                 │
│  ┌─────────────────┐    ┌─────────────────┐                         │
│  │ Collection      │    │ Prepare-        │                         │
│  │ Manifests       │───▶│ Extension.ps1   │                         │
│  │ *.collection.yml     │ -Collection     │                         │
│  └─────────────────┘    └─────────────────┘                         │
└─────────────────────────────────────────────────────────────────────┘

Collection Item Structure

Each collection item defines inclusion metadata for artifact selection and release channel filtering:

items:
    - path: .github/agents/hve-core/rpi-agent.agent.md
        kind: agent
        maturity: stable
    - path: .github/prompts/hve-core/task-plan.prompt.md
        kind: prompt
        maturity: preview

Field	Purpose
`path`	Repository-relative path to the artifact source
`kind`	Artifact type (`agent`, `prompt`, `instruction`, `skill`, `hook`)
`maturity`	Optional release channel gating value (`stable` default)

Collection Model

Collections represent role-targeted artifact packages. Collection manifests select artifacts for those roles.

Collection	Identifier	Maturity	Target Users
Full	`hve-core-all`	Stable	Universal inclusion
Core	`hve-core`	Stable	RPI workflow, code review, PR agents
ADO	`ado`	Stable	Azure DevOps integration
GitHub	`github`	Stable	GitHub backlog and issue management
Project Planning	`project-planning`	Stable	Architecture, requirements, agile coaching
Coding Standards	`coding-standards`	Stable	Language-specific coding conventions
Data Science	`data-science`	Stable	Notebooks, dashboards, data analysis
Security	`security`	Stable	Security review, planning, and incident response
RAI Planning	`rai-planning`	Experimental	Responsible AI assessment and impact analysis
Design Thinking	`design-thinking`	Preview	9-method DT coaching and learning
Installer	`installer`	Stable	HVE-Core installation and setup
Experimental	`experimental`	Experimental	Early-stage artifacts under active iteration

The Full collection aggregates artifacts from all other stable and preview collections. Role-specific collections allow targeted installation for teams that need only a subset.

Collection Build System

Collections define role-filtered artifact packages. Each collection manifest specifies which artifacts to include and controls release channel eligibility through a maturity field:

{
    "id": "data-science",
    "name": "hve-data-science",
    "displayName": "HVE Core - Data Science",
    "description": "AI-powered agents for data analysis, notebooks, and dashboards",
    "maturity": "stable",
    "items": ["data-science"]
}

The build system resolves collections by:

Reading the collection manifest to identify target artifacts
Checking collection-level maturity against the target release channel
Filtering collection items by path/kind membership
Including the hve-core-all collection artifacts as the base
Adding collection-specific artifacts
Resolving dependencies for included artifacts

Collection Maturity

Collections carry their own maturity level, independent of artifact-level maturity. This controls whether the entire collection is built for a given release channel:

Collection Maturity	PreRelease Channel	Stable Channel
`stable`	Included	Included
`preview`	Included	Included
`experimental`	Included	Excluded
`deprecated`	Excluded	Excluded

New collections should start as experimental until validated, then graduate through preview to stable by changing a single field. The maturity field is optional and defaults to stable when omitted.

Dependency Resolution

Agents may declare dependencies on other artifacts through the requires field. The dependency resolver ensures complete artifact graphs are installed:

graph TD
    A[rpi-agent] --> B[task-researcher]
    A --> C[task-planner]
    A --> D[task-implementor]
    A --> E[task-reviewer]
    A --> F[checkpoint.prompt]
    A --> G[rpi.prompt]

When installing rpi-agent, all dependent agents and prompts are automatically included regardless of collection filter.

Extension Integration

The VS Code extension discovers and activates AI artifacts through contribution points.

Discovery Mechanism

The extension scans these directories at startup:

.github/prompts/{collection-id}/ for workflow entry points
.github/agents/{collection-id}/ for specialized behaviors
.github/instructions/{collection-id}/ for technology standards
.github/skills/{collection-id}/ for utility packages

These paths reflect the conventional directory structure. Artifact inclusion is controlled by collections/*.collection.yml, and collection manifests can reference artifacts from any subfolder. Root-level artifacts (files directly under .github/{type}/ with no subdirectory) are repo-specific, excluded from discovery, and never packaged into extension builds.

Maturity	Stable Channel	Pre-release Channel
`stable`	Included	Included
`preview`	Excluded	Included
`experimental`	Excluded	Included
`deprecated`	Excluded	Excluded

The maturity table above applies to individual artifacts. Collections also carry a maturity field that gates the entire package at the channel level (see Collection Maturity).

Collection Packages

Each collection produces two distributable outputs from the same codebase: a VS Code extension (.vsix) and a Copilot CLI plugin (under plugins/).

Collection	Extension ID	Contents
Core (flagship)	`ise-hve-essentials.hve-core`	RPI workflow and core artifacts
Full	`ise-hve-essentials.hve-core-all`	All stable and preview artifacts combined
ADO	`ise-hve-essentials.hve-ado`	Azure DevOps integration
GitHub	`ise-hve-essentials.hve-github`	GitHub backlog and issue management
Project Planning	`ise-hve-essentials.hve-project-planning`	Architecture, requirements, agile coaching
Coding Standards	`ise-hve-essentials.hve-coding-standards`	Language-specific coding conventions
Data Science	`ise-hve-essentials.hve-data-science`	Notebooks, dashboards, data analysis
Security	`ise-hve-essentials.hve-security`	Security review, planning, and threat modeling
Design Thinking	`ise-hve-essentials.hve-design-thinking`	9-method DT coaching and learning
Installer	`ise-hve-essentials.hve-installer`	HVE Core installation and setup
Experimental	`ise-hve-essentials.hve-experimental`	Early-stage artifacts under active iteration

The VS Code extension is built with Prepare-Extension.ps1 and Package-Extension.ps1, parameterized by collection manifest. The Copilot CLI plugin is generated by npm run plugin:generate, which creates symlink-based plugin structures under plugins/{collection-id}/. Both outputs derive their artifact lists from the same collections/*.collection.yml source of truth.

Users install the collection matching their role for a curated experience. The Core extension provides the RPI workflow essentials, while the Full extension aggregates artifacts from all stable and preview collections.

Activation Context

Instructions activate based on the current file's path matching applyTo: patterns. Prompts and agents activate through explicit user invocation. Skills activate when agents or users request their utilities.

The extension provides these contribution points:

/prompt <name> invokes prompts by filename.
Agents activate through prompt references or direct invocation.
Matching instructions inject into Copilot context automatically.

Deprecated Artifacts

Artifacts that have been superseded or are scheduled for removal live under .github/deprecated/{type}/, preserving the same type subdirectories used by active artifacts.

Location

.github/deprecated/
├── agents/         # Superseded agent files
├── instructions/   # Retired instruction files
├── prompts/        # Retired prompt files
└── skills/         # Retired skill packages

Automatic Exclusion

The build system excludes .github/deprecated/ contents from all downstream surfaces:

Surface	Exclusion Mechanism
Collection manifests	`Update-HveCoreAllCollection` path filter
Plugin generation	`Get-ArtifactFiles` path filter
Extension packaging	Discovery function `deprecated` path filter
VS Code activation	Not discovered at runtime

No manual removal from manifests is required when an artifact moves to .github/deprecated/. The path-based exclusion operates independently of maturity metadata, providing a reliable safety net against silent reintroduction.

Retention and Removal

Deprecated artifacts remain in the repository for traceability and migration guidance. Each deprecated file SHOULD contain a frontmatter note or heading that identifies its replacement. Permanent removal occurs at a planned retirement window with a corresponding changelog entry.

When to Deprecate

Move an artifact to .github/deprecated/{type}/ when:

A newer artifact fully replaces its functionality
The artifact is no longer maintained or tested
The artifact targets a retired platform or workflow

FilesExpand file tree

ai-artifacts.md

Latest commit

History

ai-artifacts.md

File metadata and controls

Artifact Type Hierarchy

Prompts

Core Characteristics

Frontmatter Structure

Agents

Core Characteristics

Frontmatter Structure

Instructions

Core Characteristics

Frontmatter Structure

Repo-Specific Instructions

Skills

Core Characteristics

Directory Structure (by Convention)

Frontmatter Structure

Required Frontmatter Fields

Key Distinction from Instructions

Delegation Flow

Flow Mechanics

Interface Contracts

Prompt-to-Agent References

Instruction Glob Patterns

Skill Entry Points

Collection Manifests

Collection Architecture

Collection Item Structure

Collection Model

Collection Build System

Collection Maturity

Dependency Resolution

Extension Integration

Discovery Mechanism

Collection Packages

Activation Context

Deprecated Artifacts

Location

Automatic Exclusion

Retention and Removal

When to Deprecate

Related Documentation