`openspec init --global`: Install skills and commands to tool global directories

[askpatrickw]

openspec init --global: Install skills and commands to tool global directories instead of project directories

Problem

openspec init and openspec update always install skills and commands into the current project directory (e.g. .claude/skills/, .cursor/commands/). This works well when you want to commit OpenSpec tooling into a repo you own, but it creates a real problem for consultants, agencies, and developers who work across many client repositories they don't control.

The current behavior forces a choice between:

• Committing OpenSpec files into a client repo (often not acceptable)
• Manually re-running openspec init and maintaining skills in every project (high friction, no central update path)

This is already partially solved for schemas — ~/.local/share/openspec/schemas/ is a documented global path that works across all projects without touching any repo. Skills and commands need the same treatment.

Several supported tools already have first-class global installation paths:

Tool	Global path
Claude Code	~/.claude/skills/ and ~/.claude/commands/
OpenCode	~/.config/opencode/skills/ and ~/.config/opencode/commands/
Codex	~/.codex/prompts/ (already implemented this way today)

Codex is a proof of concept that this already works inside OpenSpec's own codebase — its configurator returns an absolute path rather than a project-relative one, which is exactly the pattern this feature extends to the other tools.

Proposed Implementation

The fix is a targeted extension to the existing configurator interface, not a new subsystem.

Each tool configurator currently implements two abstract methods on SlashCommandConfigurator:

abstract getRelativePath(commandId: string): string   // project-local path
abstract getFrontmatter(commandId: string): string

The proposal is to add a third:

abstract getGlobalPath(commandId: string): string | null
// Returns an absolute path if the tool has a known global directory
// Returns null if the tool has no global filesystem path (Cursor, Windsurf, etc.)

The base class generateAll() already handles file writing. It would route to getGlobalPath() instead of getRelativePath() when --global is passed, and skip/warn for configurators that return null. The existing marker-based updateExisting() logic applies unchanged — if the file exists at the global path with OpenSpec markers, it gets updated; if not, it was never globally installed. No separate manifest or tracking file is needed.

Example implementations:

// claude.ts
getGlobalPath(commandId: string): string | null {
  const base = process.platform === 'win32'
    ? path.join(process.env.APPDATA!, 'Claude')
    : path.join(os.homedir(), '.claude')
  return path.join(base, 'skills', `openspec-${commandId}`, 'SKILL.md')
}

// opencode.ts
getGlobalPath(commandId: string): string | null {
  const base = process.env.XDG_CONFIG_HOME
    ? path.join(process.env.XDG_CONFIG_HOME, 'opencode')
    : path.join(os.homedir(), '.config', 'opencode')
  return path.join(base, 'skills', `openspec-${commandId}`, 'SKILL.md')
}

// cursor.ts
getGlobalPath(commandId: string): string | null {
  return null  // Cursor has no global filesystem path for commands
}

The Codex configurator already returns an absolute path from getRelativePath(). It should be migrated to getGlobalPath() as part of this change, with getRelativePath() restored to return a project-local path. This makes the intent explicit and consistent across all configurators.

CLI surface

# Install globally — --tools required to avoid surprising writes to home dirs
openspec init --global --tools claude,opencode

# Install globally for all tools that have a known global path
openspec init --global --tools all

# Preview what would be written without touching anything
openspec init --global --tools claude --dry-run

# Update all globally-installed skills to latest templates
openspec update --global

# Remove globally-installed files
openspec uninstall --global --tools claude
openspec uninstall --global --tools all

An env var OPENSPEC_GLOBAL_ROOT overrides the base path for all global installs, useful for testing and enterprise setups where home directories are managed centrally.

Global path reference by tool and OS

Tool	macOS	Linux	Windows	Notes
Claude Code	~/.claude/	~/.claude/	%APPDATA%\Claude\	Skills → skills/openspec-*/, commands → commands/openspec/
OpenCode	~/.config/opencode/	~/.config/opencode/	%APPDATA%\opencode\	Respects $XDG_CONFIG_HOME
Codex	~/.codex/prompts/	~/.codex/prompts/	%USERPROFILE%\.codex\prompts\	Already global — migrate to getGlobalPath()
Cursor	❌	❌	❌	Global rules are UI-only in Cursor settings
Windsurf	❌	❌	❌	Project-local only
Others	❌ unknown	❌ unknown	❌ unknown	Return null; skip with warning

macOS note: Claude Code and OpenCode use ~/.claude/ and ~/.config/opencode/ rather than ~/Library/Application Support/. OpenSpec should follow each tool's own documented convention.

Windows note: Windows paths should be confirmed against each tool's actual behaviour before implementation. Prefer "unknown / not yet supported" over a guess.

Acceptance Criteria

Configurator interface

• SlashCommandConfigurator base class gains an abstract getGlobalPath(commandId): string | null method
• All existing configurators implement getGlobalPath() — returning an absolute path or null
• The Codex configurator is migrated so getRelativePath() returns a project-local path and getGlobalPath() returns the existing absolute path — behaviour unchanged, intent made explicit
• The base class generateAll() accepts a { global: boolean } option and routes to getGlobalPath() vs getRelativePath() accordingly
• Configurators returning null from getGlobalPath() are skipped when --global is used, with a per-tool warning printed to stderr

CLI behaviour

• openspec init --global --tools claude writes skills and commands to Claude Code's global directory — not to CWD
• openspec init --global --tools opencode writes to OpenCode's global directory
• openspec init --global without --tools exits with a non-zero error: "--tools is required with --global. Use --tools all to install for all tools with a known global path."
• openspec init --global --tools cursor (tool with no global path) exits with a non-zero error and a clear message
• openspec init --global --tools all installs for all tools where getGlobalPath() returns non-null, and prints a summary of installed vs skipped
• openspec init --global --dry-run prints what would be written without creating any files
• openspec update --global regenerates globally-installed files using the existing marker-based update logic
• openspec update (without --global) does not modify globally-installed files
• openspec uninstall --global --tools <id> removes OpenSpec-owned files from the tool's global directory
• OPENSPEC_GLOBAL_ROOT env var overrides the base path used in all getGlobalPath() implementations

Compatibility

• Global and project-local installations coexist — project-local takes precedence, consistent with Claude Code and OpenCode's own resolution order
• All existing project-local behaviour is unchanged
• Codex continues to install globally — behaviour unchanged, implementation cleaned up

Discoverability

• openspec init --help documents --global, notes that --tools is required, and lists which tools support global installation
• openspec schema which --all (or equivalent) indicates whether each tool's skills are installed globally, locally, or both

Why this approach

The configurator registry is already the source of truth for what gets installed where. Adding getGlobalPath() keeps global path knowledge co-located with each tool's existing path definitions rather than in a separate manifest or lookup table. The Codex configurator demonstrates the pattern already works — this change makes it explicit and extends it consistently across the tools that support it.

[1code-async]

Task completed.

The enrichment comment has been posted on issue #752. Here's a summary of the key findings:

Architecture mismatch: The issue references SlashCommandConfigurator, but the codebase uses a ToolCommandAdapter interface pattern (src/core/command-generation/types.ts). The proposed getGlobalPath() method would need to be added to this interface instead.

Key files identified:

• ToolCommandAdapter interface: src/core/command-generation/types.ts:32-48
• Codex adapter (existing global path precedent): src/core/command-generation/adapters/codex.ts
• Init command: src/core/init.ts (line 565 already handles absolute paths for Codex)
• Update command: src/core/update.ts (same pattern at line 218)
• CLI registration: src/cli/index.ts
• All 23 adapters registered in src/core/command-generation/registry.ts

Notable gaps:

• The uninstall command doesn't exist as a top-level command — only completion uninstall exists
• --dry-run doesn't exist anywhere in the CLI
• Skills are generated through a separate path (AIToolOption.skillsDir) from commands (ToolCommandAdapter), so the global path logic needs to cover both systems

4 related issues were identified (#511, #689, #723, #697) that overlap with this feature request.

---

View full conversation

Powered by 1Code

[1code-async]

Codebase Analysis

The issue references a SlashCommandConfigurator base class, but the codebase has since been refactored to use a ToolCommandAdapter interface pattern. Here's a mapping of the proposal to the current architecture:

Current Architecture (not SlashCommandConfigurator)

The interface that needs modification is ToolCommandAdapter in src/core/command-generation/types.ts:32-48:

export interface ToolCommandAdapter {
  toolId: string;
  getFilePath(commandId: string): string;   // ← equivalent of the old getRelativePath()
  formatFile(content: CommandContent): string;
}

The proposed getGlobalPath() method would be added to this interface.

Codex Adapter — Existing Global Path Precedent

The Codex adapter at src/core/command-generation/adapters/codex.ts:31-33 already returns an absolute path from getFilePath(), confirming the pattern the issue describes:

getFilePath(commandId: string): string {
  return path.join(getCodexHome(), 'prompts', `opsx-${commandId}.md`);
}

It respects CODEX_HOME env var (line 19). This is the existing proof-of-concept for global installation.

All 23 Adapters That Need getGlobalPath()

Every adapter is registered in src/core/command-generation/registry.ts:40-63. The adapters that should return non-null from getGlobalPath() based on the issue:

Adapter	File	Current getFilePath()	Proposed getGlobalPath()
claudeAdapter	adapters/claude.ts:41-42	.claude/commands/opsx/<id>.md	~/.claude/commands/opsx/<id>.md
opencodeAdapter	adapters/opencode.ts:19-20	.opencode/command/opsx-<id>.md	~/.config/opencode/command/opsx-<id>.md
codexAdapter	adapters/codex.ts:31-32	Already absolute ~/.codex/prompts/opsx-<id>.md	Migrate here from getFilePath()

All other adapters (cursor, windsurf, cline, etc.) would return null.

CLI Entry Points to Modify

1. init command — src/cli/index.ts:93-132: Add --global option. Currently accepts --tools, --force, --profile.

2. InitCommand class — src/core/init.ts:92-784: The generateSkillsAndCommands() method (line 499) handles file writing. At line 565, it already checks path.isAbsolute(cmd.path) for Codex — this is exactly where global routing needs to happen:

   const commandFile = path.isAbsolute(cmd.path) ? cmd.path : path.join(projectPath, cmd.path);

3. update command — src/cli/index.ts:156-170: Add --global option.

4. UpdateCommand class — src/core/update.ts:75-702: Same path.isAbsolute() pattern at line 218.

5. uninstall command — Does not exist as a top-level command. Currently only completion uninstall exists (line 389). A new openspec uninstall --global --tools <id> command would need to be created from scratch.

Skill Files Also Need Global Support

The issue mentions commands, but skills also need the global path treatment. Skills are generated in InitCommand.generateSkillsAndCommands() at src/core/init.ts:537-551:

const skillsDir = path.join(projectPath, tool.skillsDir, 'skills');

For global mode, the skillsDir would need to resolve to the tool's global base instead of projectPath + tool.skillsDir. The AIToolOption.skillsDir field in src/core/config.ts:17 is always project-relative (e.g., .claude, .opencode). A parallel globalBaseDir or similar field may be needed on AIToolOption, or the resolution logic could live entirely in the adapter.

--tools Validation Already Exists

The resolveToolsArg() method at src/core/init.ts:359-420 already handles all, none, and comma-separated tool IDs with validation. The --global requirement for --tools can hook into this existing validation.

--dry-run Does Not Exist

There is no --dry-run flag anywhere in the current CLI. This would be a new capability. The file writing goes through FileSystemUtils.writeFile() — a dry-run mode could intercept at that level or at the generation step in generateSkillsAndCommands().

Test Files to Extend

• test/core/command-generation/adapters.test.ts — Tests all adapter getFilePath() and formatFile() methods. Each adapter getting getGlobalPath() needs test coverage here.
• test/core/command-generation/generator.test.ts — Tests generateCommand() and generateCommands().
• test/core/command-generation/registry.test.ts — Tests CommandAdapterRegistry.
• test/core/init.test.ts — Tests InitCommand.

Related Issues

• Instructions for adding OpenSpec as Claude Skills #511 — "Instructions for adding OpenSpec as Claude Skills" — A user asking about global ~/.claude/skills/ installation. This feature would directly address that request.
• Proposal: use a standard .agent/skills folder for all agents that support it #689 — "Proposal: use a standard .agent/skills folder for all agents that support it" — Related discussion about standardizing skill folder locations across agents.
• /prompt invocation broken in Codex while $skill works #723 — "/prompt invocation broken in Codex while $skill works" — Related to Codex's global path behavior and the prompt-to-skill migration.
• Feedback: Support custom openspec/ directory path #697 — "Support custom openspec/ directory path" — Related theme of configurable installation paths.

Suggested Implementation Approach

Given the current architecture, a minimal implementation path:

1. Add getGlobalPath() to ToolCommandAdapter interface in types.ts — as an optional method to avoid breaking existing adapters:

   getGlobalPath?(commandId: string): string | null;

2. Implement in claude, opencode, codex adapters — return absolute paths. Refactor codex's getFilePath() to return a project-relative path and move the absolute path to getGlobalPath().

3. Add global option to InitCommandOptions in init.ts:81-86 and route generateSkillsAndCommands() accordingly.

4. Add --global flag to CLI in cli/index.ts for both init and update commands.

5. Create uninstall command — new top-level command, since it doesn't exist today.

6. Add OPENSPEC_GLOBAL_ROOT env var support — similar to how Codex already supports CODEX_HOME in adapters/codex.ts:19.

One design consideration: the issue proposes getGlobalPath() on the command adapter, but skills are generated separately from commands (they go through AIToolOption.skillsDir + template rendering, not through ToolCommandAdapter). The global path logic for skills may need to live in a different place — potentially on AIToolOption itself or in a new skills adapter layer — rather than only on ToolCommandAdapter.

[askpatrickw]

I fed both those into CLaude as part of the code review on my PR. They had all been addressed as claude was coding.