# How to Create and Manage Collections of AI Artifacts for Team Distribution

> Learn to create and manage AI artifact collections for team distribution using .collection.yml manifests and Validate-Collections.ps1. Streamline your AI asset sharing with hve-core.

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

---

**You can create and manage collections of AI artifacts for team distribution by defining a [`.collection.yml`](https://github.com/microsoft/hve-core/blob/main/.collection.yml) manifest that references agents, prompts, instructions, and skills stored under `.github/`, then validating the collection with `Validate-Collections.ps1` before packaging it for distribution.**

The **HVE-Core** repository from Microsoft implements a lightweight, file-system-based model to package AI artifacts for cross-team sharing. This guide explains how to leverage the collection helpers in `CollectionHelpers.psm1` and the validation logic in `Validate-Collections.ps1` to create and manage collections of AI artifacts for team distribution.

## Core Concepts for AI Artifact Collections

### Collection Manifests

A **collection** is defined by a [`.collection.yml`](https://github.com/microsoft/hve-core/blob/main/.collection.yml) (or `.json`) manifest stored in the `collections/` directory. The manifest lists metadata (`id`, `name`, `description`, `tags`) and the artifacts it contains. For example, [`collections/hve-core.collection.yml`](https://github.com/microsoft/hve-core/blob/main/collections/hve-core.collection.yml) defines the core HVE workflow artifacts.

### Artifact Types and File Conventions

Artifacts are stored under `.github/` in type-specific subdirectories:

- **Agents**: `.github/agents/*.agent.md`
- **Prompts**: `.github/prompts/*.prompt.md`
- **Instructions**: `.github/instructions/*.instructions.md`
- **Skills**: `.github/skills/*/SKILL.md` (subfolder containing [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md))

The file suffix determines the artifact *kind*, as implemented in the `suffixToKind` lookup table at lines 36-40 of `CollectionHelpers.psm1`.

### Collection Scoping and Deprecation

The system distinguishes between **repo-specific** and **collection-scoped** artifacts:

- **Repo-specific**: Root-level files under `.github/agents/` (not in a subfolder) are filtered out by `Test-HveCoreRepoSpecificPath` (lines 42-66 of `CollectionHelpers.psm1`) and excluded from distribution.
- **Collection-scoped**: Files placed in subfolders (e.g., `.github/agents/hve-core/`) are included in the collection.

**Deprecated artifacts** containing `/deprecated/` in their path are automatically excluded by `Test-DeprecatedPath` in the same module.

## Step-by-Step Guide to Create and Manage Collections

### Step 1: Create AI Artifacts with Proper Naming

Create files under the appropriate `.github` subdirectory using the correct suffix:

```markdown
---
description: "Generate a pull-request summary for reviewers."
---

You are a PR summarizer. Analyze the provided diff and produce a concise summary...

```

Save this as [`.github/prompts/my-team/summary.prompt.md`](https://github.com/microsoft/hve-core/blob/main/.github/prompts/my-team/summary.prompt.md). The front-matter is parsed by `Get-ArtifactFrontmatter` (lines 90-120 of `CollectionHelpers.psm1`).

### Step 2: Define the Collection Manifest

Create or edit [`collections/my-team.collection.yml`](https://github.com/microsoft/hve-core/blob/main/collections/my-team.collection.yml):

```yaml
id: my-team
name: My Team AI Toolkit
description: A set of reusable agents and prompts for the X team.
tags:
  - workflow
  - agents
  - prompts
items:
  - path: .github/agents/my-team/my-agent.agent.md
    kind: agent
  - path: .github/prompts/my-team/summary.prompt.md
    kind: prompt
  - path: .github/instructions/my-team/setup.instructions.md
    kind: instruction
  - path: .github/skills/my-team/my-skill
    kind: skill
display:
  ordering: manual

```

The `path` is repo-relative, and `kind` must match the suffix mapping used in `Get-ArtifactFiles` (lines 307-381 of `CollectionHelpers.psm1`).

### Step 3: Validate Collections with PowerShell

Run the built-in validator to catch orphaned files, duplicate keys, and maturity conflicts:

```powershell

# From the repository root

.\scripts\collections\Validate-Collections.ps1

```

The validator uses `Get-ArtifactFiles` to discover on-disk artifacts and cross-checks them against manifests. Typical output includes:

```

FAIL duplicate agent artifact key 'my-agent' found at distinct paths: .github/agents/hve-core/my-agent.agent.md, .github/agents/other-collection/my-agent.agent.md
WARN orphan: '.github/prompts/hve-core/old.prompt.md' is on disk but absent from 'hve-core'

```

Fix reported issues and re-run until the validator reports `Success`.

### Step 4: Distribute Collections to Teams

Collections are consumed by extensions or automation pipelines:

1. **Package** the collection (zip the manifest plus referenced files).
2. **Publish** to a shared location (internal registry, Azure Artifacts, or GitHub release).
3. **Consume** in another repository by loading the manifest via `Get-CollectionManifest`.

Example consumption snippet:

```powershell
Import-Module PowerShell-Yaml
$manifest = Get-CollectionManifest -CollectionPath 'my-team.collection.yml'

foreach ($item in $manifest.items) {
    Write-Host "Loading $($item.kind): $($item.path)"
    # Custom import logic here

}

```

## PowerShell Code Examples for Collection Management

### Creating a New Prompt Artifact

```powershell

# Create the file with front-matter

$promptPath = '.github/prompts/hve-core/summary.prompt.md'
@'
---
description: "Summarize a PR for reviewers."
---
You are a PR summarizer...
'@ | Set-Content -Path $promptPath

# Update the collection manifest

$manifestPath = 'collections/hve-core.collection.yml'
$manifest = Get-CollectionManifest -CollectionPath $manifestPath

$manifest.items += @{
    path = $promptPath
    kind = 'prompt'
}

$manifest | ConvertTo-Yaml | Set-Content -Path $manifestPath

```

### Listing All Artifacts in the Repository

```powershell
Import-Module "$PSScriptRoot/../scripts/collections/Modules/CollectionHelpers.psm1"

$repoRoot = (Get-Item "$PSScriptRoot/../..").FullName
$artifacts = Get-ArtifactFiles -RepoRoot $repoRoot

$artifacts | ForEach-Object {
    "$($_.kind): $($_.path)"
}

```

### Validating a Specific Collection

```powershell

# Validate only the hve-core collection

.\scripts\collections\Validate-Collections.ps1 -CollectionId 'hve-core'

```

## Key Files and Implementation Details

| File | Role |
|------|------|
| [`collections/hve-core.collection.yml`](https://github.com/microsoft/hve-core/blob/main/collections/hve-core.collection.yml) | Example manifest defining the core HVE workflow artifacts. |
| `scripts/collections/Modules/CollectionHelpers.psm1` | Core library containing `Get-ArtifactFiles`, `Test-DeprecatedPath`, `Test-HveCoreRepoSpecificPath`, and `Get-ArtifactFrontmatter`. |
| `scripts/collections/Validate-Collections.ps1` | End-to-end validation script that checks for orphaned files, duplicate keys, and maturity conflicts across all collections. |
| `scripts/tests/collections/CollectionHelpers.Tests.ps1` | Pester test suite documenting expected behavior for artifact discovery and path filtering. |
| `.github/agents/hve-core/*.agent.md` | Example agent artifacts (e.g., [`rpi-agent.agent.md`](https://github.com/microsoft/hve-core/blob/main/rpi-agent.agent.md)). |
| `.github/prompts/hve-core/*.prompt.md` | Example prompt artifacts (e.g., [`task-plan.prompt.md`](https://github.com/microsoft/hve-core/blob/main/task-plan.prompt.md)). |
| `.github/instructions/hve-core/*.instructions.md` | Example instruction artifacts (e.g., [`markdown.instructions.md`](https://github.com/microsoft/hve-core/blob/main/markdown.instructions.md)). |
| `.github/skills/*/SKILL.md` | Example skill directories containing [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md) files. |

## Summary

- **Collections** are defined by [`.collection.yml`](https://github.com/microsoft/hve-core/blob/main/.collection.yml) manifests stored in the `collections/` directory that reference AI artifacts under `.github/`.
- **Artifacts** use strict file suffixes ([`.agent.md`](https://github.com/microsoft/hve-core/blob/main/.agent.md), [`.prompt.md`](https://github.com/microsoft/hve-core/blob/main/.prompt.md), [`.instructions.md`](https://github.com/microsoft/hve-core/blob/main/.instructions.md), or [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md) in a subfolder) to determine their kind.
- **Scoping** distinguishes between repo-specific root-level files (excluded from distribution) and collection-scoped subfolder artifacts (included).
- **Validation** via `Validate-Collections.ps1` ensures no orphaned files, duplicate keys, or deprecated artifacts are distributed.
- **Distribution** involves packaging the manifest and referenced files for consumption by other repositories via `Get-CollectionManifest`.

## Frequently Asked Questions

### What file suffixes are required for AI artifacts in HVE-Core?

HVE-Core recognizes four artifact types based on file naming conventions. Agents use `*.agent.md`, prompts use `*.prompt.md`, instructions use `*.instructions.md`, and skills are defined by a [`SKILL.md`](https://github.com/microsoft/hve-core/blob/main/SKILL.md) file inside a subfolder under `.github/skills/`. These suffixes are mapped to artifact kinds in the `suffixToKind` table within `CollectionHelpers.psm1`.

### How does the validation script detect orphaned files?

The `Validate-Collections.ps1` script calls `Get-ArtifactFiles` from `CollectionHelpers.psm1` to discover all on-disk artifacts under `.github/`. It then cross-references these paths against the `items` listed in each [`.collection.yml`](https://github.com/microsoft/hve-core/blob/main/.collection.yml) manifest. Any artifact present on disk but absent from its corresponding manifest generates a `WARN orphan` message, indicating the file is not being distributed with the collection.

### Can I include deprecated artifacts in a collection?

No, deprecated artifacts are automatically excluded from collections. The `Test-DeprecatedPath` function in `CollectionHelpers.psm1` filters out any file path containing a `/deprecated/` segment. When `Get-ArtifactFiles` scans the repository, it applies this filter to ensure deprecated items are not discoverable for inclusion in manifests, preventing outdated artifacts from being distributed to teams.

### What is the difference between repo-specific and collection-scoped artifacts?

Repo-specific artifacts are stored at the root level of `.github/` subdirectories (e.g., [`.github/agents/my-agent.agent.md`](https://github.com/microsoft/hve-core/blob/main/.github/agents/my-agent.agent.md)) and are filtered out by `Test-HveCoreRepoSpecificPath` in `CollectionHelpers.psm1`. These are intended for repository maintenance only. Collection-scoped artifacts are placed in subfolders (e.g., [`.github/agents/hve-core/my-agent.agent.md`](https://github.com/microsoft/hve-core/blob/main/.github/agents/hve-core/my-agent.agent.md)) and are included in the distribution manifest, making them available for team consumption across multiple repositories.