microsoft / microsoft/agent-host-protocol

Add a native `argumentHint` field to `SkillCustomization` for slash-command argument help

Open Beginner friendly
#303 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

under-discussion
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

  • SkillCustomization carries id / uri / name / icons? / range? / description? / disableModelInvocation?.
  • RuleCustomization already shows the spec's established style of modeling skill/rule behavior with first-class, type-specific fields (alwaysApply, globs) rather than a generic bag.
  • AgentCustomization has a _meta slot; SkillCustomization does 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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.