docs: document __SPECKIT_COMMAND_ token for portable cross-command references#3503
Open
Quratulain-bilal wants to merge 2 commits into
Open
docs: document __SPECKIT_COMMAND_ token for portable cross-command references#3503Quratulain-bilal wants to merge 2 commits into
Quratulain-bilal wants to merge 2 commits into
Conversation
the development guide's 'Body (Markdown)' section listed $ARGUMENTS and
{SCRIPT} but never mentioned __SPECKIT_COMMAND_<NAME>__, the agent-neutral
token that resolve_command_refs() renders into each agent's invocation
syntax. with no signal the token exists, an author naturally hard-codes a
literal like /speckit.my-ext.prepare — correct for one agent, broken on the
rest (the root cause behind github#3451).
added it to the placeholder list plus a 'Referencing other commands'
subsection: why a literal isn't portable, the name->token encoding, and a
worked example showing the same token render as /speckit.bug.fix for a
slash agent and /speckit-bug-fix for a skills agent. examples verified
against resolve_command_refs and the first-party bug/git extensions.
phase 1 of the plan in github#3474; addresses the discoverability gap for github#3451.
Contributor
There was a problem hiding this comment.
Pull request overview
Documents the portable __SPECKIT_COMMAND_<NAME>__ placeholder in the extension development guide so extension authors can reference other commands without hard-coding agent-specific invocation syntax.
Changes:
- Adds
__SPECKIT_COMMAND_<NAME>__to the command-body placeholder list. - Introduces a “Referencing other commands” subsection explaining the token’s purpose, encoding rules, and an example.
- Notes a naming limitation around underscores/hyphens in command-name segments.
Show a summary per file
| File | Description |
|---|---|
| extensions/EXTENSION-DEVELOPMENT-GUIDE.md | Documents the cross-command reference token, its encoding, and provides usage guidance/examples for extension authors. |
Review details
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 1
- Review effort level: Low
Comment on lines
+273
to
+276
| A command body is a *template* that Spec Kit renders once per agent. Different agents invoke commands with different surface syntax — slash-based agents use `/speckit.plan`, skills-based agents use `/speckit-plan`, and some (Codex, Zcode) use `$speckit-plan` in skills mode. So when you reference a sibling command from a body, **do not hard-code a literal invocation** like `/speckit.my-ext.prepare`. A literal is correct for exactly one agent and breaks on the rest. | ||
|
|
||
| Instead use the agent-neutral token `__SPECKIT_COMMAND_<NAME>__`. Spec Kit resolves it to the correct invocation for whichever agent the project is initialized with. | ||
|
|
Collaborator
|
Can you please address Copilot feedback. We will should tackle the documentation change for skill rendering once that lands. Thanks! |
Copilot flagged (and mnriem asked me to address) that the section implied __SPECKIT_COMMAND_<NAME>__ always resolves to each agent's native invocation, including $speckit-* for Codex/ZCode. the resolver (resolve_command_refs) only emits /speckit<separator>... based on the active integration's invoke_separator; the $ and /skill: prefixes come from later skills-output post-processing, not the token resolver itself. reworded both the placeholder-list entry and the two explanatory paragraphs to describe separator-based rendering, and moved the prefix-in-skills-mode detail to a parenthetical example rather than stating it as the token's guaranteed output.
Contributor
Author
|
addressed in 8fb401a. you're right resolve_command_refs only emits /speckit... based on the active integration's invoke_separator; the $ and /skill: prefixes come from later skills-output post-processing, not the token resolver itself. reworded the placeholder-list entry and both paragraphs to describe separator-based rendering, and moved the skills-mode prefix detail (Kimi /skill:, Codex/ZCode $) into a parenthetical example rather than stating it as the token's guaranteed output. @mnriem agreed on holding the fuller skill-rendering docs until that work lands happy to follow up with it then. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
phase 1 of the plan @mnriem laid out in #3474: document the
__SPECKIT_COMMAND_<NAME>__token so extension authors have a signal it exists.why
the development guide's "Body (Markdown)" section listed
$ARGUMENTSand{SCRIPT}but never mentioned__SPECKIT_COMMAND_<NAME>__— the agent-neutral token thatresolve_command_refs()(integrations/base.py) renders into each agent's own invocation syntax. with no mention of it, an author naturally hard-codes a literal like/speckit.my-ext.prepare, which is correct for one agent and breaks on the rest. that literal-instead-of-token mistake is the root cause behind #3451.what
docs-only, in EXTENSION-DEVELOPMENT-GUIDE.md:
speckit.prefix dropped, dotted segments -> underscores), and a worked example_back to the agent separator, so a token can't carry a hyphen inside a name segmentverification
every rendered example in the docs was checked against
resolve_command_refsdirectly — e.g.__SPECKIT_COMMAND_BUG_FIX__->/speckit.bug.fix(slash) and/speckit-bug-fix(skills). the token names match the first-partybugandgitextensions, which use this token exclusively.scope: this is the independent, shippable docs increment. phases 2 (wire token resolution into the skill render path) and 3 (codex
$speckit-override) from the #3474 plan are separate.