microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/architecture/ai-artifacts.md
486lines · modecode
| 1 | --- |
| 2 | title: AI Artifacts Architecture |
| 3 | description: Prompt, agent, and instruction delegation model for Copilot customizations |
| 4 | sidebar_position: 2 |
| 5 | author: Microsoft |
| 6 | ms.date: 2026-03-10 |
| 7 | ms.topic: concept |
| 8 | --- |
| 9 | |
| 10 | 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. |
| 11 | |
| 12 | ## Artifact Type Hierarchy |
| 13 | |
| 14 | The artifact system organizes customizations by scope and responsibility. Prompts handle user interaction, agents orchestrate workflows, instructions encode standards, and skills provide executable utilities. |
| 15 | |
| 16 | ### Prompts |
| 17 | |
| 18 | Prompts (`.prompt.md`) serve as workflow entry points. They capture user intent and translate requests into structured guidance for Copilot execution. |
| 19 | |
| 20 | #### Core Characteristics |
| 21 | |
| 22 | * Define single-session workflows with clear inputs and outputs |
| 23 | * Accept user inputs through `${input:varName}` template syntax |
| 24 | * Delegate to agents via `agent:` frontmatter references |
| 25 | |
| 26 | #### Frontmatter Structure |
| 27 | |
| 28 | ```yaml |
| 29 | --- |
| 30 | description: 'Protocol for creating ADO pull requests' |
| 31 | agent: Task Planner |
| 32 | --- |
| 33 | ``` |
| 34 | |
| 35 | Prompts answer the question "what does the user want to accomplish?" and route execution to appropriate agents. |
| 36 | |
| 37 | ### Agents |
| 38 | |
| 39 | Agents (`.agent.md`) define task-specific behaviors with access to Copilot tools. They orchestrate multi-step workflows and make decisions based on context. |
| 40 | |
| 41 | #### Core Characteristics |
| 42 | |
| 43 | * Specify available tools through `tools:` frontmatter arrays |
| 44 | * Enable workflow handoffs via `handoffs:` references to other agents |
| 45 | * Maintain conversation context across multiple interactions |
| 46 | * Apply domain expertise through detailed behavioral instructions |
| 47 | |
| 48 | #### Frontmatter Structure |
| 49 | |
| 50 | ```yaml |
| 51 | --- |
| 52 | description: 'Orchestrates task planning with research integration' |
| 53 | tools: ['codebase', 'search', 'editFiles', 'changes'] |
| 54 | handoffs: |
| 55 | - label: "⚡ Implement" |
| 56 | agent: Task Implementor |
| 57 | prompt: /task-implement |
| 58 | send: true |
| 59 | - label: "🔬 Research" |
| 60 | agent: Task Researcher |
| 61 | prompt: /task-research |
| 62 | send: true |
| 63 | --- |
| 64 | ``` |
| 65 | |
| 66 | Agents answer the question "how should this task be executed?" and coordinate the necessary tools and resources. |
| 67 | |
| 68 | ### Instructions |
| 69 | |
| 70 | Instructions (`.instructions.md`) encode technology-specific standards and conventions. They apply automatically based on file patterns and provide consistent guidance across the codebase. |
| 71 | |
| 72 | #### Core Characteristics |
| 73 | |
| 74 | * Match files through `applyTo:` glob patterns for automatic application |
| 75 | * Define coding standards, naming conventions, and quality requirements |
| 76 | * Apply to specific languages, frameworks, or file types |
| 77 | * Stack with other instructions when multiple patterns match |
| 78 | |
| 79 | #### Frontmatter Structure |
| 80 | |
| 81 | ```yaml |
| 82 | --- |
| 83 | description: 'Python scripting standards with type hints' |
| 84 | applyTo: '**/*.py, **/*.ipynb' |
| 85 | --- |
| 86 | ``` |
| 87 | |
| 88 | Instructions answer the question "what standards apply to this context?" and ensure consistent code quality. |
| 89 | |
| 90 | #### Repo-Specific Instructions |
| 91 | |
| 92 | 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. |
| 93 | |
| 94 | > [!IMPORTANT] |
| 95 | > 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. |
| 96 | |
| 97 | ### Skills |
| 98 | |
| 99 | 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. |
| 100 | |
| 101 | #### Core Characteristics |
| 102 | |
| 103 | * Provide self-contained utility packages with documentation and scripts |
| 104 | * Include parallel implementations for cross-platform support (`.sh` and `.ps1`) |
| 105 | * Execute actual operations rather than providing guidance |
| 106 | |
| 107 | #### Directory Structure (by Convention) |
| 108 | |
| 109 | ```text |
| 110 | .github/skills/{collection-id}/<skill-name>/ |
| 111 | ├── SKILL.md # Required entry point with frontmatter |
| 112 | ├── scripts/ |
| 113 | │ ├── convert.sh # Bash implementation |
| 114 | │ └── convert.ps1 # PowerShell implementation |
| 115 | └── examples/ |
| 116 | └── README.md # Usage examples |
| 117 | ``` |
| 118 | |
| 119 | #### Frontmatter Structure |
| 120 | |
| 121 | ```yaml |
| 122 | --- |
| 123 | name: video-to-gif |
| 124 | description: 'Video-to-GIF conversion with FFmpeg optimization' |
| 125 | --- |
| 126 | ``` |
| 127 | |
| 128 | #### Required Frontmatter Fields |
| 129 | |
| 130 | | Field | Description | |
| 131 | |---------------|---------------------------------------------------------| |
| 132 | | `name` | Lowercase kebab-case identifier matching directory name | |
| 133 | | `description` | Brief capability description | |
| 134 | |
| 135 | Maturity is tracked in `collections/*.collection.yml`, not in skill frontmatter. See [Collection Manifests](#collection-manifests) for details. |
| 136 | |
| 137 | Skills answer the question "what specialized utility does this task require?" and provide executable capabilities beyond conversational guidance. |
| 138 | |
| 139 | #### Key Distinction from Instructions |
| 140 | |
| 141 | | Aspect | Instructions | Skills | |
| 142 | |------------|-----------------------------|-----------------------| |
| 143 | | Nature | Passive reference | Active execution | |
| 144 | | Content | Standards and conventions | Scripts and utilities | |
| 145 | | Activation | Automatic via glob patterns | Explicit invocation | |
| 146 | | Output | Guidance for Copilot | Executed operations | |
| 147 | |
| 148 | ## Delegation Flow |
| 149 | |
| 150 | The artifact system follows a hierarchical delegation model. User requests flow through prompts to agents, which apply relevant instructions during execution. |
| 151 | |
| 152 | ```mermaid |
| 153 | graph LR |
| 154 | USER[User Request] --> PROMPT[Prompt] |
| 155 | PROMPT --> AGENT[Agent] |
| 156 | AGENT --> INSTR[Instructions] |
| 157 | AGENT --> SKILLS[Skills] |
| 158 | ``` |
| 159 | |
| 160 | ### Flow Mechanics |
| 161 | |
| 162 | 1. User invokes a prompt through `/prompt` commands or workflow triggers. |
| 163 | 2. Prompt references an agent via `agent:` frontmatter, delegating execution. |
| 164 | 3. Agent executes with instructions auto-applied based on file context. |
| 165 | 4. Agent invokes skills for specialized utilities with executable scripts. |
| 166 | |
| 167 | This delegation model separates concerns. Prompts handle user interaction, agents manage orchestration, and instructions provide standards. |
| 168 | |
| 169 | ## Interface Contracts |
| 170 | |
| 171 | Each artifact type defines clear interfaces for interoperability. |
| 172 | |
| 173 | ### Prompt-to-Agent References |
| 174 | |
| 175 | Prompts reference agents through the `agent:` frontmatter field: |
| 176 | |
| 177 | ```yaml |
| 178 | --- |
| 179 | description: 'Create a pull request with work item linking' |
| 180 | agent: 'pr-creator' |
| 181 | --- |
| 182 | ``` |
| 183 | |
| 184 | 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. |
| 185 | |
| 186 | ### Instruction Glob Patterns |
| 187 | |
| 188 | Instructions use `applyTo:` patterns for automatic activation: |
| 189 | |
| 190 | | Pattern | Matches | |
| 191 | |------------------------------|--------------------------------------| |
| 192 | | `**/*.py` | All Python files recursively | |
| 193 | | `**/tests/**/*.ts` | TypeScript files in test directories | |
| 194 | | `**/.copilot-tracking/pr/**` | PR tracking files | |
| 195 | |
| 196 | Multiple instructions can apply to the same file. When patterns overlap, all matching instructions contribute guidance. Pattern specificity determines precedence for conflicting directives. |
| 197 | |
| 198 | ### Skill Entry Points |
| 199 | |
| 200 | Skills provide self-contained utilities through the `SKILL.md` file: |
| 201 | |
| 202 | ```text |
| 203 | .github/skills/{collection-id}/<skill-name>/ |
| 204 | ├── SKILL.md # Entry point documentation |
| 205 | ├── convert.sh # Bash implementation |
| 206 | ├── convert.ps1 # PowerShell implementation |
| 207 | └── examples/ |
| 208 | └── README.md |
| 209 | ``` |
| 210 | |
| 211 | The `{collection-id}` path segment reflects the conventional organization; artifacts can reside in any subfolder. |
| 212 | |
| 213 | 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. |
| 214 | |
| 215 | ## Collection Manifests |
| 216 | |
| 217 | 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. |
| 218 | |
| 219 | ### Collection Architecture |
| 220 | |
| 221 | ```text |
| 222 | ┌─────────────────────────────────────────────────────────────────────┐ |
| 223 | │ Collection Manifests │ |
| 224 | │ collections/*.collection.yml │ |
| 225 | │ ┌─────────────────────────────────────────────────────────────┐ │ |
| 226 | │ │ items[] │ │ |
| 227 | │ │ - path │ │ |
| 228 | │ │ - kind │ │ |
| 229 | │ │ - maturity (optional, defaults to stable) │ │ |
| 230 | │ └─────────────────────────────────────────────────────────────┘ │ |
| 231 | └─────────────────────────────────────────────────────────────────────┘ |
| 232 | │ |
| 233 | ▼ |
| 234 | ┌─────────────────────────────────────────────────────────────────────┐ |
| 235 | │ Build System │ |
| 236 | │ ┌─────────────────┐ ┌─────────────────┐ │ |
| 237 | │ │ Collection │ │ Prepare- │ │ |
| 238 | │ │ Manifests │───▶│ Extension.ps1 │ │ |
| 239 | │ │ *.collection.yml │ -Collection │ │ |
| 240 | │ └─────────────────┘ └─────────────────┘ │ |
| 241 | └─────────────────────────────────────────────────────────────────────┘ |
| 242 | ``` |
| 243 | |
| 244 | ### Collection Item Structure |
| 245 | |
| 246 | Each collection item defines inclusion metadata for artifact selection and release channel filtering: |
| 247 | |
| 248 | ```yaml |
| 249 | items: |
| 250 | - path: .github/agents/hve-core/rpi-agent.agent.md |
| 251 | kind: agent |
| 252 | maturity: stable |
| 253 | - path: .github/prompts/hve-core/task-plan.prompt.md |
| 254 | kind: prompt |
| 255 | maturity: preview |
| 256 | ``` |
| 257 | |
| 258 | | Field | Purpose | |
| 259 | |------------|-------------------------------------------------------------------| |
| 260 | | `path` | Repository-relative path to the artifact source | |
| 261 | | `kind` | Artifact type (`agent`, `prompt`, `instruction`, `skill`, `hook`) | |
| 262 | | `maturity` | Optional release channel gating value (`stable` default) | |
| 263 | |
| 264 | ### Collection Model |
| 265 | |
| 266 | Collections represent role-targeted artifact packages. Collection manifests select artifacts for those roles. |
| 267 | |
| 268 | | Collection | Identifier | Maturity | Target Users | |
| 269 | |----------------------|--------------------|--------------|--------------------------------------------------| |
| 270 | | **Full** | `hve-core-all` | Stable | Universal inclusion | |
| 271 | | **Core** | `hve-core` | Stable | RPI workflow, code review, PR agents | |
| 272 | | **ADO** | `ado` | Stable | Azure DevOps integration | |
| 273 | | **GitHub** | `github` | Stable | GitHub backlog and issue management | |
| 274 | | **Project Planning** | `project-planning` | Stable | Architecture, requirements, agile coaching | |
| 275 | | **Coding Standards** | `coding-standards` | Stable | Language-specific coding conventions | |
| 276 | | **Data Science** | `data-science` | Stable | Notebooks, dashboards, data analysis | |
| 277 | | **Security** | `security` | Stable | Security review, planning, and incident response | |
| 278 | | **RAI Planning** | `rai-planning` | Experimental | Responsible AI assessment and impact analysis | |
| 279 | | **Design Thinking** | `design-thinking` | Preview | 9-method DT coaching and learning | |
| 280 | | **Installer** | `installer` | Stable | HVE-Core installation and setup | |
| 281 | | **Experimental** | `experimental` | Experimental | Early-stage artifacts under active iteration | |
| 282 | |
| 283 | 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. |
| 284 | |
| 285 | ### Collection Build System |
| 286 | |
| 287 | Collections define role-filtered artifact packages. Each collection manifest specifies which artifacts to include and controls release channel eligibility through a `maturity` field: |
| 288 | |
| 289 | ```json |
| 290 | { |
| 291 | "id": "data-science", |
| 292 | "name": "hve-data-science", |
| 293 | "displayName": "HVE Core - Data Science", |
| 294 | "description": "AI-powered agents for data analysis, notebooks, and dashboards", |
| 295 | "maturity": "stable", |
| 296 | "items": ["data-science"] |
| 297 | } |
| 298 | ``` |
| 299 | |
| 300 | The build system resolves collections by: |
| 301 | |
| 302 | 1. Reading the collection manifest to identify target artifacts |
| 303 | 2. Checking collection-level maturity against the target release channel |
| 304 | 3. Filtering collection items by path/kind membership |
| 305 | 4. Including the `hve-core-all` collection artifacts as the base |
| 306 | 5. Adding collection-specific artifacts |
| 307 | 6. Resolving dependencies for included artifacts |
| 308 | |
| 309 | #### Collection Maturity |
| 310 | |
| 311 | Collections carry their own maturity level, independent of artifact-level maturity. This controls whether the entire collection is built for a given release channel: |
| 312 | |
| 313 | | Collection Maturity | PreRelease Channel | Stable Channel | |
| 314 | |---------------------|--------------------|----------------| |
| 315 | | `stable` | Included | Included | |
| 316 | | `preview` | Included | Included | |
| 317 | | `experimental` | Included | Excluded | |
| 318 | | `deprecated` | Excluded | Excluded | |
| 319 | | `removed` | Excluded | Excluded | |
| 320 | |
| 321 | 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. |
| 322 | |
| 323 | ### Dependency Resolution |
| 324 | |
| 325 | Agents may declare dependencies on other artifacts through the `requires` field. The dependency resolver ensures complete artifact graphs are installed: |
| 326 | |
| 327 | ```mermaid |
| 328 | graph TD |
| 329 | A[rpi-agent] --> B[task-researcher] |
| 330 | A --> C[task-planner] |
| 331 | A --> D[task-implementor] |
| 332 | A --> E[task-reviewer] |
| 333 | A --> F[checkpoint.prompt] |
| 334 | A --> G[rpi.prompt] |
| 335 | ``` |
| 336 | |
| 337 | When installing `rpi-agent`, all dependent agents and prompts are automatically included regardless of collection filter. |
| 338 | |
| 339 | ## Extension Integration |
| 340 | |
| 341 | The VS Code extension discovers and activates AI artifacts through contribution points. |
| 342 | |
| 343 | ### Discovery Mechanism |
| 344 | |
| 345 | The extension scans these directories at startup: |
| 346 | |
| 347 | * `.github/prompts/{collection-id}/` for workflow entry points |
| 348 | * `.github/agents/{collection-id}/` for specialized behaviors |
| 349 | * `.github/instructions/{collection-id}/` for technology standards |
| 350 | * `.github/skills/{collection-id}/` for utility packages |
| 351 | |
| 352 | 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. |
| 353 | |
| 354 | | Maturity | Stable Channel | Pre-release Channel | |
| 355 | |----------------|----------------|---------------------| |
| 356 | | `stable` | Included | Included | |
| 357 | | `preview` | Excluded | Included | |
| 358 | | `experimental` | Excluded | Included | |
| 359 | | `deprecated` | Excluded | Excluded | |
| 360 | | `removed` | Excluded | Excluded | |
| 361 | |
| 362 | 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-maturity)). |
| 363 | |
| 364 | ### Collection Packages |
| 365 | |
| 366 | Each collection produces two distributable outputs from the same codebase: a VS Code extension (`.vsix`) and a Copilot CLI plugin (under `plugins/`). |
| 367 | |
| 368 | | Collection | Extension ID | Contents | |
| 369 | |------------------|-------------------------------------------|------------------------------------------------| |
| 370 | | Core (flagship) | `ise-hve-essentials.hve-core` | RPI workflow and core artifacts | |
| 371 | | Full | `ise-hve-essentials.hve-core-all` | All stable and preview artifacts combined | |
| 372 | | ADO | `ise-hve-essentials.hve-ado` | Azure DevOps integration | |
| 373 | | GitHub | `ise-hve-essentials.hve-github` | GitHub backlog and issue management | |
| 374 | | Project Planning | `ise-hve-essentials.hve-project-planning` | Architecture, requirements, agile coaching | |
| 375 | | Coding Standards | `ise-hve-essentials.hve-coding-standards` | Language-specific coding conventions | |
| 376 | | Data Science | `ise-hve-essentials.hve-data-science` | Notebooks, dashboards, data analysis | |
| 377 | | Security | `ise-hve-essentials.hve-security` | Security review, planning, and threat modeling | |
| 378 | | Design Thinking | `ise-hve-essentials.hve-design-thinking` | 9-method DT coaching and learning | |
| 379 | | Installer | `ise-hve-essentials.hve-installer` | HVE Core installation and setup | |
| 380 | | Experimental | `ise-hve-essentials.hve-experimental` | Early-stage artifacts under active iteration | |
| 381 | |
| 382 | 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. |
| 383 | |
| 384 | 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. |
| 385 | |
| 386 | ### Activation Context |
| 387 | |
| 388 | 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. |
| 389 | |
| 390 | The extension provides these contribution points: |
| 391 | |
| 392 | * `/prompt <name>` invokes prompts by filename. |
| 393 | * Agents activate through prompt references or direct invocation. |
| 394 | * Matching instructions inject into Copilot context automatically. |
| 395 | |
| 396 | ## Deprecated Artifacts |
| 397 | |
| 398 | Artifacts that have been superseded or are scheduled for removal live under `.github/deprecated/{type}/`, preserving the same type subdirectories used by active artifacts. |
| 399 | |
| 400 | ### Location |
| 401 | |
| 402 | ```text |
| 403 | .github/deprecated/ |
| 404 | ├── agents/ # Superseded agent files |
| 405 | ├── instructions/ # Retired instruction files |
| 406 | ├── prompts/ # Retired prompt files |
| 407 | └── skills/ # Retired skill packages |
| 408 | ``` |
| 409 | |
| 410 | ### Automatic Exclusion |
| 411 | |
| 412 | The build system excludes `.github/deprecated/` contents from all downstream surfaces: |
| 413 | |
| 414 | | Surface | Exclusion Mechanism | |
| 415 | |----------------------|---------------------------------------------| |
| 416 | | Collection manifests | `Update-HveCoreAllCollection` path filter | |
| 417 | | Plugin generation | `Get-ArtifactFiles` path filter | |
| 418 | | Extension packaging | Discovery function `deprecated` path filter | |
| 419 | | VS Code activation | Not discovered at runtime | |
| 420 | |
| 421 | 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. |
| 422 | |
| 423 | ### Retention and Removal |
| 424 | |
| 425 | 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. |
| 426 | |
| 427 | ### When to Deprecate |
| 428 | |
| 429 | Move an artifact to `.github/deprecated/{type}/` when: |
| 430 | |
| 431 | * A newer artifact fully replaces its functionality |
| 432 | * The artifact is no longer maintained or tested |
| 433 | * The artifact targets a retired platform or workflow |
| 434 | |
| 435 | ## Removed Artifacts |
| 436 | |
| 437 | The `removed` maturity is a collection-manifest-only marker that retires an artifact from every generated distribution while leaving its source file in place. Unlike deprecation, no file move is required and no per-artifact frontmatter field is involved - the collection YAML is the single source of truth. |
| 438 | |
| 439 | ### Collection-YAML Marker |
| 440 | |
| 441 | Mark an item as removed by setting `maturity: removed` on the collection entry: |
| 442 | |
| 443 | ```yaml |
| 444 | items: |
| 445 | - path: .github/skills/security/owasp-docker/SKILL.md |
| 446 | kind: skill |
| 447 | maturity: removed |
| 448 | ``` |
| 449 | |
| 450 | Every collection that references the artifact must carry the same marker. The artifact file itself stays under its original `.github/{type}/{collection-id}/` location, preserving git history, cross-references, and the option to reinstate it by changing a single field. |
| 451 | |
| 452 | ### Automatic Exclusion |
| 453 | |
| 454 | The collection-level `removed` marker is honored at every build stage: |
| 455 | |
| 456 | | Surface | Exclusion Mechanism | |
| 457 | |-----------------------|----------------------------------------------------------------------------------------------------------| |
| 458 | | Collection manifests | `Update-HveCoreAllCollection` and `Get-ArtifactFiles` skip items where `maturity` equals `removed` | |
| 459 | | Plugin generation | `npm run plugin:generate` produces no plugin entry for removed items | |
| 460 | | Extension packaging | `Get-AllowedMaturities` (in `Prepare-Extension.ps1`) excludes `removed` from PreRelease and Stable alike | |
| 461 | | Collection validation | `Validate-Collections.ps1` accepts `removed` as a valid `maturity` value but never emits the artifact | |
| 462 | |
| 463 | No runtime code reads a per-artifact `maturity` field; the schema for `SKILL.md` and other artifact frontmatter intentionally does not define one. This keeps the collection YAML as the unambiguous source of truth for distribution decisions. |
| 464 | |
| 465 | ### Removed vs. Deprecated vs. `.github/deprecated/` |
| 466 | |
| 467 | Three distinct mechanisms govern artifact retirement, each chosen for a different intent: |
| 468 | |
| 469 | | Mechanism | What it signals | Source file location | When to use | |
| 470 | |-------------------------------------|----------------------------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------| |
| 471 | | `maturity: deprecated` (collection) | Sunset in progress; transition time for downstream users | Original location | A replacement exists or removal is planned; users need a release window to migrate | |
| 472 | | `maturity: removed` (collection) | Withdrawn from distribution; source retained | Original location | Distribution must stop now, but the file should stay for history, cross-references, or possible future reinstatement | |
| 473 | | `.github/deprecated/{type}/` (path) | Long-term archival; replacement documented in-file | Moved subtree | The artifact is fully superseded and should be visibly archived; path-based filter prevents silent reintroduction | |
| 474 | |
| 475 | Use `maturity: removed` when the artifact should disappear from generated outputs without any source-tree disruption. Move to `.github/deprecated/` when archival visibility and a path-based safety net matter more than keeping the original location. |
| 476 | |
| 477 | ## Related Documentation |
| 478 | |
| 479 | * [Agent Systems Catalog](../agents/) - Overview of all agent systems with workflow documentation |
| 480 | * [AI Artifacts Common Standards](../contributing/ai-artifacts-common.md) - Quality requirements for all artifacts |
| 481 | * [Contributing Prompts](../contributing/prompts.md) - Prompt file specifications |
| 482 | * [Contributing Agents](../contributing/custom-agents.md) - Agent file specifications |
| 483 | * [Contributing Instructions](../contributing/instructions.md) - Instruction file specifications |
| 484 | * [Contributing Skills](../contributing/skills.md) - Skill package specifications |
| 485 | |
| 486 | 🤖 *Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.* |
| 487 | |