microsoft / microsoft/agent-host-protocol
Add a native `argumentHint` field to `SkillCustomization` for slash-command argument help
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 344
- Forks
- 122
- Avg merge
- 14h 12m
- Merged PRs (30d)
- 22
Description
Summary
SkillCustomization describes a host-discovered skill so a client can list it, show its description, and (via disableModelInvocation) reason about model auto-invocation. What it can't express is the argument hint for a user-invocable, slash-command-style skill — the short "how do I call this" string that a command palette renders next to the command (e.g. /deploy <env> [--dry-run]).
There's no field for it and no generic escape hatch: unlike AgentCustomization, SkillCustomization has no _meta slot, so a host that receives an argument hint from its runtime has to drop it. A client building a slash-command palette then can't show the user what arguments a command expects.
Current state in the spec
SkillCustomizationcarriesid/uri/name/icons?/range?/description?/disableModelInvocation?.RuleCustomizationalready shows the spec's established style of modeling skill/rule behavior with first-class, type-specific fields (alwaysApply,globs) rather than a generic bag.AgentCustomizationhas a_metaslot;SkillCustomizationdoes not — so there isn't even a non-native fallback for skill-level metadata.
Proposal
Add an optional, display-only field to SkillCustomization:
export interface SkillCustomization extends CustomizationBase {
type: CustomizationType.Skill;
description?: string;
disableModelInvocation?: boolean;
/**
* Freeform hint describing the arguments a user-invocable skill
* expects, for display in a slash-command palette or help text
* (e.g. "<env> [--dry-run]"). Absent when the skill takes no
* arguments or the source declares no hint. Display-only: hosts
* neither parse nor enforce it.
*/
argumentHint?: string;
}
- Optional, so existing producers/consumers are unaffected until they opt in.
- Display-only: a hint for humans, not a parseable arg schema. Hosts don't validate against it.
- Absent ⇒ no hint (skill takes no arguments, or the source declared none).
Concrete grounding (public, vendor SDK example)
A representative agent SDK already reports this per skill: session.skills_loaded skill entries carry an argumentHint string sourced from the skill's argument-hint frontmatter, right alongside description, enabled, and userInvocable. So the data exists at the source; only the AHP carrier field is missing.
Relationship to #285
#285 completes the child-customization model with per-child enabled and a symmetric user/model invocation matrix (disableUserInvocation / disableModelInvocation) — the whether a skill can be invoked. argumentHint is the complementary how to invoke it (argument help) datum for the user-invocable case. It's small and orthogonal enough to either fold into #285 or land on its own; filing separately so it isn't lost, and happy to consolidate if preferred.
Backwards compatibility
Purely additive and optional — no behavior change for producers or consumers until they populate/read the field.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Locate the TypeScript definition of SkillCustomization and compare its existing fields with RuleCustomization and AgentCustomization. Add the optional display-only argumentHint field with the documented semantics and example, then verify the protocol types and any relevant checks still pass.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, backend-api-design
- Issue type
- Feature
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100