microsoft/hve-core
Publicmirrored from https://github.com/microsoft/hve-coreAvailable
docs/customization/collections.md
196lines · modecode
| 1 | --- |
| 2 | title: Managing Collections |
| 3 | description: Bundle agents, prompts, instructions, and skills into distributable collection packages with maturity filtering |
| 4 | author: Microsoft |
| 5 | ms.date: 2026-02-24 |
| 6 | ms.topic: how-to |
| 7 | keywords: |
| 8 | - collections |
| 9 | - bundling |
| 10 | - distribution |
| 11 | - maturity |
| 12 | estimated_reading_time: 6 |
| 13 | --- |
| 14 | |
| 15 | ## Collection Architecture |
| 16 | |
| 17 | Collections bundle related agents, prompts, instructions, and skills into distributable |
| 18 | packages. Each collection consists of two files in the `collections/` directory: |
| 19 | |
| 20 | * A YAML manifest (`*.collection.yml`) that lists every artifact included in the collection |
| 21 | * A markdown description (`*.collection.md`) that provides human-readable documentation |
| 22 | |
| 23 | The YAML manifest defines what the collection contains. The markdown description explains |
| 24 | the collection's purpose, lists key artifacts, and helps users decide whether to install it. |
| 25 | Together, these two files form a complete, self-contained collection package that the plugin |
| 26 | generation pipeline processes into distributable output under `plugins/`. |
| 27 | |
| 28 | ## YAML Manifest Format |
| 29 | |
| 30 | Every collection manifest follows the `collection-manifest.schema.json` schema. The top-level |
| 31 | fields are: |
| 32 | |
| 33 | | Field | Required | Description | |
| 34 | |---------------|----------|-----------------------------------------------------------------------| |
| 35 | | `id` | Yes | Unique identifier (lowercase, hyphens only, e.g., `deployment-tools`) | |
| 36 | | `name` | Yes | Human-readable display name | |
| 37 | | `description` | Yes | Brief description of the collection's purpose | |
| 38 | | `maturity` | No | Collection-level maturity tier (defaults to `stable`) | |
| 39 | | `tags` | No | Array of discovery tags for filtering and search | |
| 40 | | `items` | Yes | Array of artifact entries | |
| 41 | | `display` | No | Display configuration (ordering: `alpha` or `manual`) | |
| 42 | |
| 43 | Each entry in the `items` array has these fields: |
| 44 | |
| 45 | | Field | Required | Description | |
| 46 | |------------|----------|---------------------------------------------------------------------| |
| 47 | | `path` | Yes | Relative path from repo root to the source file or directory | |
| 48 | | `kind` | Yes | Artifact type: `agent`, `prompt`, `instruction`, `skill`, or `hook` | |
| 49 | | `maturity` | No | Item-level maturity override (defaults to `stable`) | |
| 50 | | `usage` | No | Optional usage guidance for the item | |
| 51 | |
| 52 | Here is a complete manifest example: |
| 53 | |
| 54 | ```yaml |
| 55 | id: deployment-tools |
| 56 | name: Deployment Tools |
| 57 | description: CI/CD pipeline agents and deployment automation prompts |
| 58 | tags: |
| 59 | - deployment |
| 60 | - ci-cd |
| 61 | - automation |
| 62 | items: |
| 63 | # Agents |
| 64 | - path: .github/agents/deployment/pipeline-builder.agent.md |
| 65 | kind: agent |
| 66 | - path: .github/agents/deployment/rollback-advisor.agent.md |
| 67 | kind: agent |
| 68 | # Prompts |
| 69 | - path: .github/prompts/deployment/deploy-staging.prompt.md |
| 70 | kind: prompt |
| 71 | # Instructions |
| 72 | - path: .github/instructions/deployment/pipeline-standards.instructions.md |
| 73 | kind: instruction |
| 74 | - path: .github/instructions/shared/hve-core-location.instructions.md |
| 75 | kind: instruction |
| 76 | # Skills |
| 77 | - path: .github/skills/deployment/canary-analysis |
| 78 | kind: skill |
| 79 | display: |
| 80 | ordering: manual |
| 81 | ``` |
| 82 | |
| 83 | > [!NOTE] |
| 84 | > The `path` field uses repo-relative paths. Skills reference the skill directory (containing |
| 85 | > `SKILL.md`), not the `SKILL.md` file itself. |
| 86 | |
| 87 | ## Maturity Filtering |
| 88 | |
| 89 | Collections support four maturity tiers that control inclusion in generated plugin output: |
| 90 | |
| 91 | | Tier | Meaning | Plugin Inclusion | |
| 92 | |----------------|--------------------------------------------|-----------------------------| |
| 93 | | `stable` | Production-ready, fully tested | Included in all channels | |
| 94 | | `preview` | Feature-complete but undergoing validation | Included in preview channel | |
| 95 | | `experimental` | Early-stage, may change significantly | Excluded from stable builds | |
| 96 | | `deprecated` | Scheduled for removal | Excluded from new builds | |
| 97 | |
| 98 | Maturity applies at two levels: |
| 99 | |
| 100 | * **Collection-level**: Set the `maturity` field on the manifest root. A collection marked |
| 101 | `experimental` excludes all its items from the stable release channel. |
| 102 | * **Item-level**: Set the `maturity` field on individual items within the `items` array. |
| 103 | This overrides the collection-level default for specific artifacts. |
| 104 | |
| 105 | When `maturity` is omitted at either level, it defaults to `stable`. |
| 106 | |
| 107 | ## Creating a Collection |
| 108 | |
| 109 | Follow these steps to create a new collection: |
| 110 | |
| 111 | 1. Choose a collection ID. Use lowercase letters and hyphens (e.g., `sre-operations`). |
| 112 | The ID must match the pattern `^[a-z0-9-]+$`. |
| 113 | |
| 114 | 2. Create the YAML manifest at `collections/{id}.collection.yml`. Define the `id`, `name`, |
| 115 | `description`, `tags`, and `items` fields following the schema above. |
| 116 | |
| 117 | 3. Create the markdown description at `collections/{id}.collection.md`. Describe the |
| 118 | collection's purpose, list the key agents and prompts, and explain when to use it. |
| 119 | |
| 120 | 4. Register each artifact in the `items` array with its `path` and `kind`. Verify that |
| 121 | every referenced file exists at the specified path. |
| 122 | |
| 123 | 5. Run the plugin generation pipeline: |
| 124 | |
| 125 | ```bash |
| 126 | npm run plugin:generate |
| 127 | ``` |
| 128 | |
| 129 | 6. Validate the collection metadata: |
| 130 | |
| 131 | ```bash |
| 132 | npm run plugin:validate |
| 133 | ``` |
| 134 | |
| 135 | > [!TIP] |
| 136 | > Start with an existing collection YAML (such as `hve-core.collection.yml`) as a template. |
| 137 | > Copy the structure and replace the content with your artifacts. |
| 138 | |
| 139 | ## Subagent Dependencies |
| 140 | |
| 141 | When a parent agent declares subagents in its `agents:` frontmatter, those subagent files |
| 142 | must also appear in the collection YAML. The plugin generation pipeline does not |
| 143 | automatically resolve transitive agent dependencies. |
| 144 | |
| 145 | For example, if `rpi-agent.agent.md` references `phase-implementor.agent.md` as a subagent, |
| 146 | both files must have entries in the collection manifest: |
| 147 | |
| 148 | ```yaml |
| 149 | items: |
| 150 | - path: .github/agents/hve-core/rpi-agent.agent.md |
| 151 | kind: agent |
| 152 | - path: .github/agents/hve-core/subagents/phase-implementor.agent.md |
| 153 | kind: agent |
| 154 | ``` |
| 155 | |
| 156 | Omitting a subagent causes the parent agent to lose access to that capability when installed |
| 157 | from the collection. |
| 158 | |
| 159 | ## The hve-core-all Superset |
| 160 | |
| 161 | The `hve-core-all.collection.yml` manifest serves as the canonical superset of all stable |
| 162 | artifacts across every collection. It aggregates items from specialized collections (such |
| 163 | as `hve-core`, `ado`, `github`, `project-planning`) into a single comprehensive bundle. |
| 164 | |
| 165 | Update `hve-core-all.collection.yml` when you: |
| 166 | |
| 167 | * Add a new artifact to any collection |
| 168 | * Create an entirely new collection |
| 169 | * Remove or deprecate an existing artifact |
| 170 | |
| 171 | The superset collection ensures users who install the full bundle receive every available |
| 172 | artifact. Items marked with `maturity: experimental` or `maturity: deprecated` at the item |
| 173 | level remain in the superset for visibility but are filtered during stable channel generation. |
| 174 | |
| 175 | ## Role Scenarios |
| 176 | |
| 177 | **Tailspin Toys' SRE/Operations lead** creates a `deployment-tools` collection to bundle |
| 178 | pipeline-builder agents, rollback advisors, and deployment prompts into a single |
| 179 | distributable package. The SRE team installs this collection across all service repositories, |
| 180 | giving every engineer access to standardized deployment workflows without manually copying |
| 181 | individual files. |
| 182 | |
| 183 | **Contoso's platform architect** creates a `microservices-standards` collection containing |
| 184 | API design instructions, service mesh configuration skills, and architecture review agents. |
| 185 | New teams onboarding to the microservices platform install this single collection to receive |
| 186 | all governance artifacts at once. |
| 187 | |
| 188 | ## Further Reading |
| 189 | |
| 190 | See [docs/contributing/](../contributing/) for collection validation rules and artifact |
| 191 | syntax reference. |
| 192 | |
| 193 | <!-- markdownlint-disable MD036 --> |
| 194 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 195 | then carefully refined by our team of discerning human reviewers.* |
| 196 | <!-- markdownlint-enable MD036 --> |
| 197 | |