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

You can create and manage collections of AI artifacts for team distribution by defining a .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 (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 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)

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:

---
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. 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:

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:

# 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:

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

# 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

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

# 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	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).
.github/prompts/hve-core/*.prompt.md	Example prompt artifacts (e.g., task-plan.prompt.md).
.github/instructions/hve-core/*.instructions.md	Example instruction artifacts (e.g., markdown.instructions.md).
.github/skills/*/SKILL.md	Example skill directories containing SKILL.md files.

Summary

• Collections are defined by .collection.yml manifests stored in the collections/ directory that reference AI artifacts under .github/.
• Artifacts use strict file suffixes (.agent.md, .prompt.md, .instructions.md, or 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 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 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) 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) and are included in the distribution manifest, making them available for team consumption across multiple repositories.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}