Skip to content

[Bug]: argument-hint dropped from extension commands when generating Claude SKILL.md (kept for core commands) #2903

@huy1010

Description

@huy1010

What happened

When a command supplied by an extension (specify extension add) declares argument-hint: in its frontmatter, that field is stripped from the generated Claude skill (.claude/skills/<name>/SKILL.md). The same field is correctly preserved for core template commands (e.g. clarify, analyze, implement).

So argument-hint works for built-in commands but silently disappears for extension-provided commands.

Environment

  • specify version: 0.9.2
  • Integration: claude (manifest version 0.9.2)
  • Reproduced via specify extension add --dev <extension>

Steps to reproduce

  1. Create an extension command file with argument-hint in its frontmatter:

    ---
    description: "Build and maintain a lean, static context/ knowledge folder…"
    argument-hint: "<init | update | list | check> [area] [slug] [-- notes]"
    ---
  2. Declare it in extension.yml under provides.commands (only name / file / description are supported there — there is no field for argument-hint).

  3. Install: specify extension add --dev extensions/<id>.

  4. Inspect the generated .claude/skills/<name>/SKILL.md.

Expected

argument-hint is carried into the generated SKILL.md frontmatter, the same way it is for core template commands.

Actual

argument-hint is dropped. Only name / description / compatibility / metadata survive (also user-invocable / disable-model-invocation are absent).

Evidence — two different serializers

Core command (templates/commands/clarify.md → installed skill) — kept, and every value is quoted:

---
name: "speckit-clarify"
description: "Identify underspecified areas in the current feature spec…"
argument-hint: "Optional areas to clarify in the spec"
compatibility: "Requires spec-kit project structure with .specify/ directory"
metadata:
  author: "github-spec-kit"
  source: "templates/commands/clarify.md"
user-invocable: true
disable-model-invocation: false
---

Extension command (same argument-hint in source) → installed skill — dropped, and description is unquoted/YAML-folded:

---
name: speckit-nimble-build-context
description: Build and maintain a lean, static context/ knowledge folder so coding
  agents load only what is relevant and save tokens
compatibility: Requires spec-kit project structure with .specify/ directory
metadata:
  author: github-spec-kit
  source: nimble:commands/speckit.nimble.build-context.md
---

The differing YAML style (quoted vs. unquoted-folded) suggests the extension install path uses a different frontmatter serializer than the core template path, and that serializer only whitelists name / description / compatibility / metadata.

Suggested fix

Have the extension command → skill frontmatter transformer preserve argument-hint (and ideally user-invocable / disable-model-invocation), matching the core template path added in #1951.

Workaround

Post-process the generated SKILL.md after specify extension add to re-inject argument-hint from the source command frontmatter.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions