trending/OpenSpec
1
0
Fork 0
mirror of https://github.com/Fission-AI/OpenSpec.git synced 2026-10-02 05:24:34 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs(tools): cite the Grok command source and the skills-only form

Browse Source 
Review feedback on #1851.

Documents the `/openspec-propose` spelling that skills-only delivery
produces for Grok, which the entry previously left to the general
invocation table, and pins that behavior with an assertion that no
command files are written in that mode.

Also cites `.grok/commands/` to the shipping CLI's own symbols rather
than asserting it. The published docs cover `skills/` only, so an
automated review read the directory as unsupported; `skill_config_dirs()`
returns `[".grok", ".agents", ".claude", ".cursor"]` and each is passed
to `find_command_paths`, which scans `commands/` flat.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Clay Good
2026-09-11 11:03:47 -05:00
co-authored by Claude Opus 5
parent 8d7ac40b3a
commit 347c9ee178
2 changed files with 9 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/supported-tools.md
+5 -1
View File
@@ -112,7 +112,11 @@ to read the hint.
\*\*\*\* Windsurf was [rebranded to Devin Desktop](https://docs.devin.ai/desktop/devin-desktop-faq) on June 2, 2026, and its config directory moved: `.devin/` is the preferred read + write location, `.windsurf/` a legacy read-only fallback. OpenSpec follows the rename — the tool id is `devin`, and `--tools windsurf` still resolves to it so existing setup scripts keep working. A project still holding OpenSpec files in `.windsurf/` is offered the move on the next `openspec update`; declining leaves them in place, and files you wrote yourself are never touched. Workflows are invoked by filename, so `.devin/workflows/opsx-apply.md` is `/opsx-apply`. The [Devin Local agent does not support workflows](https://docs.devin.ai/desktop/devin-local) — only skills, and it does not read `.windsurf/` at all — so whenever OpenSpec writes Devin skills it keeps their bodies, and the getting-started hint, on `/openspec-*` skill invocations, which work on both agents. Under commands-only delivery no skills are written and both fall back to `/opsx-*`.
\*\*\*\*\* Grok Build is xAI's `grok` CLI. It has no separate command subsystem: the same loader that discovers `.grok/skills/<name>/SKILL.md` also scans `.grok/commands/` and registers each Markdown file there as a slash command. That scan is flat — a nested `commands/opsx/<id>.md` is skipped, not namespaced — so OpenSpec writes `.grok/commands/opsx-<id>.md` and the filename is the command: `/opsx-propose`. The same loader also scans the `commands/` directory under `.agents/`, `.claude/`, and `.cursor/` for vendor compatibility — again, read from the shipping CLI rather than the published docs. Those directories hold `opsx/<id>.*` files, which the flat scan skips, so configuring Grok alongside Claude Code registers each command once rather than twice. [Skills](https://docs.x.ai/build/features/skills-plugins-marketplaces) are documented upstream; the `commands/` directory is read by the shipping CLI but is not yet part of the published docs.
\*\*\*\*\* Grok Build is xAI's `grok` CLI. It has no separate command subsystem: the loader that discovers `.grok/skills/<name>/SKILL.md` also scans `.grok/commands/` and registers each Markdown file there as a slash command. That scan is flat — a nested `commands/opsx/<id>.md` is skipped, not namespaced — so OpenSpec writes `.grok/commands/opsx-<id>.md` and the filename is the command: `/opsx-propose`. Under skills-only delivery no command files are written and the generated skills are invoked by name instead, as `/openspec-propose`.
The same loader also scans `commands/` under `.agents/`, `.claude/`, and `.cursor/` for vendor compatibility. Those directories hold `opsx/<id>.*` files, which the flat scan skips, so configuring Grok alongside Claude Code registers each command once rather than twice.
[Skills](https://docs.x.ai/build/features/skills-plugins-marketplaces) are documented upstream. The `commands/` directory is not yet in the published docs, so it is cited here from the shipping CLI's source: `skill_config_dirs()` returns `[".grok", ".agents", ".claude", ".cursor"]` (`crates/codegen/xai-grok-tools/src/types/compat.rs`), each of which is passed to `find_command_paths`, which reads `commands/` via `scan_md_files` — documented there as "Scan a directory for `.md` files (flat, no recursion)" (`crates/codegen/xai-grok-tools/src/implementations/skills/discovery.rs`).
SourceCraft Code Assistant support targets its VS Code extension. Its [custom commands](https://sourcecraft.dev/portal/docs/en/code-assistant/operations/agent/slash-commands) and [skills](https://sourcecraft.dev/portal/docs/ru/code-assistant/operations/agent/skills) are available only in VS Code. This integration does not configure SourceCraft web or JetBrains.
test/core/update.test.ts
+4
View File
@@ -3619,9 +3619,13 @@ More user content after markers.
const skillFile = path.join(toolDir, 'skills', 'openspec-apply-change', 'SKILL.md');
expect(await FileSystemUtils.fileExists(skillFile)).toBe(delivery === 'skills');
if (delivery === 'skills') {
// No command files are written, so skill bodies must invoke skills by
// name. Grok registers a user-invocable skill as `/<skill-name>`.
const skillContent = await fs.readFile(skillFile, 'utf-8');
expect(skillContent).toContain('/openspec-archive-change');
expect(skillContent).not.toContain('/opsx:');
expect(skillContent).not.toContain('/opsx-');
expect(await FileSystemUtils.fileExists(path.join(toolDir, 'commands', 'opsx-propose.md'))).toBe(false);
}
// Grok's own project config and the user's hand-written command and
// skill are never OpenSpec's to touch.