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.

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

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

under-discussion

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.

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

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.

More from microsoft/agent-host-protocol

All issues in microsoft/agent-host-protocol

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.