Proposal - Collections

[aaronpowell]

Discussed in #221

^{Originally posted by aaronpowell September 3, 2025}
There’s recurring feedback across PRs and issues (see #135, #167, and #169) asking for a way to signal when prompts, instructions, and chat modes are related and best used together. This proposal introduces “Collections” — a lightweight way to group related resources without adding custom frontmatter to files or forcing contributors to touch lots of places.

Mental model

A Collection represents a role, function, or scenario that benefits from several pieces working together. For example:

• Role-based: “DevOps On-Call,” “Tech Lead,” “Security Reviewer.”, "Solution Architect"
• Concept-based: “Prompt Engineering Basics,” “Code Review Toolkit.”
• Workflow-based: “Incident Triage,” “Release Readiness.”

Goals

To make Collections work, there's are the goals that I've come up with, based off the discussions and feedback we've received so far:

• Make relationships between customisation files obvious (e.g., “these prompts and this chat mode belong together”).
• Keep contribution friction low:
  • No non-standard frontmatter in the prompts/chat modes/instructions as this causes confusion in the editor (warning squiggles) and deviations from documentation.
  • Avoid “edit a bunch of files to add metadata.” as right now contributing is as simple as "create a file and up the update script", so we'd like to keep it as close to that as possible.
  • Prefer one small, centralized edit per Collection.
• Keep the implementation maintainable with validation and auto-generation where it helps.

Non-goals

• Redesigning the entire repo structure - there are limits to what we can achieve in GitHub rendered markdown files.
• Enforcing complex dependency graphs or new rendering engines.
• Mandating that all content belongs to a Collection, standalone is still fine (and likely the default for most contributions).

Collection design

To make a Collection useful, we're going to need to have some amount of additional information beyond the current files themselves, it's likely we'd want to have information such as the description of the collection and how to use it, on top of some way to indicate the files that belong to the collection.

Proposed design

The initial proposal is that we add a new folder into the repo, collections, which contains a manifest file, collections/<collection-slug>.collection.yml (or .json), that is the metadata for the Collection (see the example).

Then the update script we currently have can be extended to read the manifest and generate a README.<collection-slug>.md file (probably within the collections folder to avoid too many root-level files) and have it linked from the main README.md.

Designing it this way would see the benefits of:

• Contributors only add/update a single manifest file to define or change a Collection.
• No changes to member files required.
• Easy to validate in CI and auto-generate index pages.

Example: collections/devops-oncall.collection.yml

id: devops-oncall
name: DevOps On-Call
description: A focused set of prompts, instructions, and a chat mode to help triage incidents and respond quickly.
tags: [devops, incident-response, oncall] # optional, purely for discovery
items:
  - path: prompts/oncall-triage.prompt.md
    kind: prompt
  - path: instructions/logs-to-collect.instructions.md
    kind: instruction
  - path: chatmodes/devops-oncall.chatmodes.json
    kind: chat-mode
  - path: prompts/devops-postmortem-template.prompt.md
    kind: prompt
display:
  ordering: manual # optional: manual | alpha
  show_badge: true  # optional

Notes:

• kind is a small, controlled vocabulary (prompt | instruction | chat-mode).
• items.path is a relative repo root path; files can live anywhere (no reorg required).
• Optional fields let us add discovery aids without touching content files.

Contribution flow

• New Collection:
  • Create collections/<slug>.collection.yml with id, name, description, and items - this is something we could likely automate with VS Code tasks or a shell script.
  • Runs the update-readme.js.
  • Open PR. CI validates manifest and paths.
• Update Collection:
  • Edit the manifest (add/remove item paths).
  • Runs the update-readme.js.
• Add a new item to an existing Collection:
  • Add the new file in its natural home (e.g., prompts/…).
  • Add a single line to the manifest items list referencing its path.

Tooling and automation

• VS Code task to create a new Collection
• GitHub Copilot prompt and instructions for creating/editing a Collection
• Validation (GitHub Action):
  • Ensure id uniqueness across collections.
  • Verify each items.path exists.
  • Verify kind {prompt, instruction, chat-mode}.
  • Warn editing files that are part of a Collection to review that they are still relevant.
• Auto-generated index:
  • A script generates collections/README.md (and update the top-level README section) from manifests:
    • List all Collections with name, description, tags.
    • For each Collection, list member items with links.
  • Generate a specific Collection README for deep-linking.
• JSON Schema for manifests:
  • Publish schema in repo (e.g., .schemas/collection.schema.json).
  • CI validation + editor hints for contributors.

Migration plan

• Seed 1–2 pilot Collections that mirror the relationships discussed in Collection category #135, Dependency instructions #167, and Reusable Prompts #169.
• Add CI validation + generation in the same PR (scoped to collections/).
• Iterate on schema with real content before broad adoption.

Open questions for feedback

• Naming: “Collection”, “Bundle”, “Kit”, “Pack”, something else?
• Manifest format: YAML or JSON? (Leaning YAML for readability.)
• Placement: a flat collections/*.yml vs collections/<slug>/collection.yml?
• Ordering: Should we support per-Collection manual ordering (proposed) and/or per-kind sorting?
• Multi-membership: Allow the same item in multiple Collections? (Default yes; helps reuse.)
• Tags: Keep lightweight optional tags for discovery or skip initially?
• Display: Where should we surface Collections in README/docs for best UX?
• How do we handle downloads, given this isn't a native feature of the editors GitHub Copilot supports.

Alternatives considered

• Frontmatter-based membership in each file:
  • Rejected per requirements (no non-standard frontmatter, many edits).
• Directory-only membership (put everything in the same folder):
  • Simple but inflexible; many resources live across existing structures.
  • Harder to reuse an item in multiple Collections.
• Single global collections.yml:
  • Centralized but creates merge hotspots and makes reviews noisy.
  • Per-Collection files scale better.

Risks and mitigations

• Risk: Manifest drift (files moved/removed).
  • Mitigation: CI validation checks paths.
• Risk: Fragmentation of naming/structure.
  • Mitigation: Provide a short “How to create a Collection” guide + schema.
• Risk: Overhead for contributors.
  • Mitigation: One-file edit; clear examples; optional tooling to scaffold manifests.

Next steps

1. Agree on the concept and naming.
2. Finalize manifest schema and location.
3. Add CI validation + auto-generated index (scoped).
4. Pilot with a couple of Collections reflecting the scenarios from Collection category #135, Dependency instructions #167, Reusable Prompts #169.
5. Document “How to create a Collection” with a copy-paste template.

Appendix: minimal manifest template

id: <slug>
name: <Human-friendly name>
description: <Short description of why these items belong together>
items:
  - path: <relative/path/to/file.md>
    kind: <prompt|instruction|chat-mode>

Would love feedback on the above, especially on naming, manifest format, and where we should surface Collections in the repo for the best contributor and reader experience.