feat: add Grok Build skills-only support

[0x6d6e647a]

Summary

• add Grok Build as a supported OpenSpec tool with skillsDir: '.grok'
• document Grok Build as a skills-only integration using /openspec-* skill invocations
• add a focused init regression test for adapterless command generation
• add a spec-driven change proposal for the Grok Build support work (archived as 2026-07-11-add-grok-build-skills-only-support)

Technical Analysis

Grok Build does not expose a stable project-local file-based custom command surface like Claude Code or Codex. Its documented extension model is skill discovery from ./.grok/skills/ (and ~/.grok/skills/), and user-invocable skills appear as slash commands (/<skill-name>). Core TUI commands (/plan, /model, /skills, …) are built-in, not OpenSpec-generated project files. Because of that, this change treats Grok Build as a skills-only tool and does not add a grok command adapter.

The OpenSpec implementation follows the same narrow adapterless pattern merged for Kimi CLI:

• skills-only precedent: #1003 feat: add Kimi CLI skills-only support
• related skills-only tools already in tree: ForgeCode (.forge), Mistral Vibe (.vibe)

Upstream docs used for the integration surface:

• Grok Build overview
• Skills, Plugins & Marketplaces — project skills at ./.grok/skills/, skills surface as /<skill-name>
• Modes and Commands — skill-as-command form; no documented .grok/commands/ project layout for custom opsx files

This intentionally does not rely on Grok’s Claude/Cursor compatibility scanners as the product integration. Free-riding on .claude/skills can work for some users, but it couples Grok support to Claude layout, can be disabled via Grok config/env, and never registers Grok as a configured OpenSpec tool for init/update. Native .grok remains the canonical target.

Tool metadata:

{ name: 'Grok Build', value: 'grok', available: true, successLabel: 'Grok Build', skillsDir: '.grok' }

Validation

• openspec validate add-grok-build-skills-only-support --strict (pre-archive)
• pnpm exec vitest run test/core/init.test.ts -t "Grok Build"

Summary by CodeRabbit

• New Features

  • Added support for Grok Build as a skills-only integration.
  • Grok skills are generated in the .grok/skills directory.
  • Grok uses /openspec-* skill invocations instead of generated command files.

• Documentation

  • Added Grok Build to supported tool lists, command references, and troubleshooting guidance.
  • Documented that command generation is skipped for tools without adapters.

[coderabbitai]

📝 Walkthrough

Walkthrough

Grok Build is added as a supported skills-only tool with skillsDir: '.grok'. Initialization generates Grok skills, skips command-file generation without an adapter, documents the behavior, and adds regression coverage.

Changes

Grok Build skills-only support

Layer / File(s)	Summary
Behavior contracts openspec/changes/archive/..., openspec/specs/...	Specifications define .grok skill paths and skipping command-file generation for adapterless tools.
Tool registration and init coverage src/core/config.ts, test/core/init.test.ts, openspec/changes/archive/.../tasks.md	Registers Grok Build and verifies skill creation, absent .grok/commands, and the skip log.
CLI and tool documentation docs/*.md	Documents the grok ID, skill-based invocations, supported paths, and troubleshooting guidance.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant InitCommand
  participant AI_TOOLS
  participant SkillGeneration
  participant CommandAdapterRegistry
  InitCommand->>AI_TOOLS: resolve grok with skillsDir .grok
  InitCommand->>SkillGeneration: generate skills under .grok/skills
  InitCommand->>CommandAdapterRegistry: look up Grok adapter
  CommandAdapterRegistry-->>InitCommand: no adapter registered
  InitCommand-->>InitCommand: skip command-file generation and log reason

Loading

Possibly related PRs

• Fission-AI/OpenSpec#318: Extends the shared AI_TOOLS registry with another supported tool.
• Fission-AI/OpenSpec#1003: Covers the adapterless skills-only initialization flow and skipped command generation.

Suggested reviewers: alfred-openspec, TabishB

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: adding Grok Build as a supported skills-only tool.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/how-commands-work.md (1)

83-87: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Clarify Grok’s slash-based skill invocation.

The new row correctly uses /openspec-propose, but the surrounding guidance says skill-based tools use skills “instead of slash commands” while the page’s generic instructions still direct users to /opsx. Qualify those instructions or explicitly state that Grok uses /openspec-* slash-invoked skills.

Suggested wording

-| Grok Build | skill-style, e.g. `/openspec-propose` |
+| Grok Build | skill-style slash invocation, e.g. `/openspec-propose` |

-A few tools surface OpenSpec as named skills instead of slash commands; for those you invoke the skill by name.
+Some tools surface OpenSpec as named skills; use the tool-specific slash syntax shown above.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/how-commands-work.md` around lines 83 - 87, Clarify the guidance in
docs/how-commands-work.md to explicitly state that Grok invokes its skills
through /openspec-* slash commands, while other named-skill tools may use
non-slash invocation. Align the generic instructions with the Grok Build row and
existing /opsx guidance without changing the command mappings.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@docs/how-commands-work.md`:
- Around line 83-87: Clarify the guidance in docs/how-commands-work.md to
explicitly state that Grok invokes its skills through /openspec-* slash
commands, while other named-skill tools may use non-slash invocation. Align the
generic instructions with the Grok Build row and existing /opsx guidance without
changing the command mappings.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e0e690d2-4e58-4560-a084-18b5c0d97647

📥 Commits

Reviewing files that changed from the base of the PR and between 0a99f41 and 9e78d4c.

📒 Files selected for processing (15)

• docs/cli.md
• docs/commands.md
• docs/how-commands-work.md
• docs/supported-tools.md
• docs/troubleshooting.md
• openspec/changes/archive/2026-07-11-add-grok-build-skills-only-support/.openspec.yaml
• openspec/changes/archive/2026-07-11-add-grok-build-skills-only-support/design.md
• openspec/changes/archive/2026-07-11-add-grok-build-skills-only-support/proposal.md
• openspec/changes/archive/2026-07-11-add-grok-build-skills-only-support/specs/ai-tool-paths/spec.md
• openspec/changes/archive/2026-07-11-add-grok-build-skills-only-support/specs/cli-init/spec.md
• openspec/changes/archive/2026-07-11-add-grok-build-skills-only-support/tasks.md
• openspec/specs/ai-tool-paths/spec.md
• openspec/specs/cli-init/spec.md
• src/core/config.ts
• test/core/init.test.ts