Add a native `argumentHint` field to `SkillCustomization` for slash-command argument help
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 72/100
- Issue type
- Feature
- Clarity
- Clearly specified
- Activity status
- Quiet
- Tech stack
- typescript
- Domain
- api, backend-api-design
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.
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.
- Dominant language
- TypeScript
- Stars
- 348
- Forks
- 122
- Avg merge
- 14h 12m
- Merged PRs (30d)
- 22
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.
More from microsoft/agent-host-protocol
-
Difficulty 4/5 3-5 days Newbie friendliness 55/100
microsoft/agent-host-protocol#452 · 1 comment ·
-
Difficulty 5/5 Over a week Newbie friendliness 45/100
microsoft/agent-host-protocol#446 ·
-
Difficulty 5/5 Over a week Newbie friendliness 35/100
microsoft/agent-host-protocol#444 · 1 comment ·
-
Difficulty 3/5 1-2 days Newbie friendliness 68/100
microsoft/agent-host-protocol#432 ·
-
Difficulty 4/5 3-5 days Newbie friendliness 48/100
microsoft/agent-host-protocol#426 ·
All issues in microsoft/agent-host-protocol
Similar issues
-
calcite-components needs triage refactor
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Esri/calcite-design-system#15203 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 91/100
-
community first-timers-only good first issue hacktoberfest help wanted low hanging fruit up-for-grabs
Difficulty 1/5 Under an hour Newbie friendliness 95/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Automattic/studio#4908 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 90/100