microsoft / microsoft/agent-host-protocol

Add a non-directory grouping container for host-discovered customizations

Open
#287 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
344
Forks
122
Avg merge
14h 12m
Merged PRs (30d)
22

Description

Summary

SkillCustomization and AgentCustomization are ChildCustomizations, so they must live under a top-level container. But the only container variants are Plugin and Directory. A host that surfaces customizations it discovered itself — grouped by a logical source/scope that is not a real watched directory and not an Open Plugins plugin — has no honest container to put them in. Please add a generic grouping container variant.

Current state in the spec (0.4.0)

  • Customization (top-level) is one of Plugin / Directory / McpServer. (Skill, Agent, Prompt, Rule, Hook are ChildCustomizations only — they can't be top-level.)
  • DirectoryCustomization is documented as a directory the host watches; it carries writable and a file://-style uri, and a load state.
  • There is no neutral "labeled group of children" container.

The problem

To surface, say, skills/agents grouped by origin (project vs. user vs. some other logical scope) that don't correspond 1:1 to a watched directory, a host has to reuse DirectoryCustomization with writable: false and a synthesized, non-file:// uri standing in for the logical source. That's a semantic stretch: it claims a filesystem directory exists where one doesn't, and it overloads a uri that consumers may reasonably expect to be a real path.

Proposal

Add a Customization::Group (GroupCustomization) top-level variant: a labeled, non-filesystem collection of ChildCustomizations. Suggested fields:

  • id — stable container id (for toggling / addressing).
  • name — human label for the group/source.
  • children — the contained ChildCustomizations.
  • enabled — container enable/disable (consistent with Plugin / Directory).
  • load — a load/diagnostic state (consistent with Directory), so a group can report its own load health, errors, and warnings.
  • icons / range — optional, for parity with the other customizations.
  • optionally an origin / source descriptor for the logical scope.

This models host-discovered, non-file-backed groupings honestly, and is generally useful to any host that surfaces customizations it found itself rather than from a plugin or a watched directory.

Backwards compatibility

A new top-level enum variant is additive; existing producers and consumers are unaffected until they emit or read it. (Consumers that exhaustively match on the Customization variants will need to handle the new case — standard for any new variant.)

Relationship to other proposals

All three are independent; this one is purely about the container a host groups children under, so any combination can land in any order.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the 0.4.0 Customization definition and compare the existing Plugin and Directory variants. Define the Group top-level variant around the proposed fields, then update any schema or exhaustive variant handling identified while tracing those definitions. Done means hosts can represent labeled, non-filesystem groups of child customizations without reusing DirectoryCustomization.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.