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
-
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]"
---
-
Declare it in extension.yml under provides.commands (only name / file / description are supported there — there is no field for argument-hint).
-
Install: specify extension add --dev extensions/<id>.
-
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.
What happened
When a command supplied by an extension (
specify extension add) declaresargument-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-hintworks for built-in commands but silently disappears for extension-provided commands.Environment
specifyversion: 0.9.2specify extension add --dev <extension>Steps to reproduce
Create an extension command file with
argument-hintin its frontmatter:Declare it in
extension.ymlunderprovides.commands(onlyname/file/descriptionare supported there — there is no field forargument-hint).Install:
specify extension add --dev extensions/<id>.Inspect the generated
.claude/skills/<name>/SKILL.md.Expected
argument-hintis carried into the generatedSKILL.mdfrontmatter, the same way it is for core template commands.Actual
argument-hintis dropped. Onlyname/description/compatibility/metadatasurvive (alsouser-invocable/disable-model-invocationare absent).Evidence — two different serializers
Core command (
templates/commands/clarify.md→ installed skill) — kept, and every value is quoted:Extension command (same
argument-hintin source) → installed skill — dropped, anddescriptionis unquoted/YAML-folded: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 ideallyuser-invocable/disable-model-invocation), matching the core template path added in #1951.Workaround
Post-process the generated
SKILL.mdafterspecify extension addto re-injectargument-hintfrom the source command frontmatter.