OpenSpec Initial Skill
Run openspec init to initialize OpenSpec in a project: creates the openspec/ directory (specs, changes, config) and configures AI tool integrations (skills and slash commands). This skill assumes the OpenSpec CLI is already installed; if not, direct the user to openspec-install first.
When to Use
- First time enabling OpenSpec in a project ("initialize OpenSpec", "set up OpenSpec here").
- Adding AI tool integrations (Claude, Cursor, Windsurf, etc.) to an existing project.
- Re-initializing after changing tool selections.
Prerequisites
- OpenSpec CLI installed (see openspec-install). If
openspecis not in PATH, guide the user to run openspec-install before proceeding.
Workflow
- Verify CLI
- If the user reports "openspec command not found", direct them to openspec-install first.
- Choose parameters
- path (optional): Target directory; defaults to current directory. - --tools (optional): Configure AI tools non-interactively. Values: all, none, or comma-separated list (e.g. claude,cursor). - --force: Auto-cleanup legacy files without prompting.
- Run the command
- Interactive: openspec init - Non-interactive with specific tools: openspec init --tools claude,cursor - All tools: openspec init --tools all - Specific directory: openspec init./my-project
- Optionally create project config
- During init, the user may be prompted to create openspec/config.yaml with project context, schema defaults, and per-artifact rules. This is optional but recommended. See openspec-config for details.
- Confirm outputs
- After success: openspec/ directory with specs/, changes/, and optionally config.yaml. Tool-specific directories (.claude/skills/, .cursor/rules/, etc.) are created based on selected tools.
Supported Tools
amazon-q, antigravity, auggie, claude, cline, codebuddy, codex, continue, costrict, crush, cursor, factory, gemini, github-copilot, iflow, kilocode, opencode, qoder, qwen, roocode, trae, windsurf
Outputs
- openspec/:
- specs/ — Specifications (source of truth) - changes/ — Proposed changes - config.yaml — Project configuration (optional)
- Tool configs:
.claude/skills/,.cursor/rules/,.windsurf/skills/, etc. based on selected tools.
Next Steps
- Use openspec-update after upgrading the CLI to regenerate tool configs.
- Use openspec-onboard for a guided walkthrough of the complete workflow.
- Or start working: openspec-explore to think through ideas, openspec-new to start a change.
Different Environments
| Scenario | Command |
|---|---|
| Interactive | openspec init |
| Claude + Cursor | openspec init --tools claude,cursor |
| All tools | openspec init --tools all |
| Specific directory | openspec init./my-project |
| CI / non-interactive | openspec init --tools claude --force |
| Skip tool config | openspec init --tools none |
Troubleshooting
- "openspec: command not found": Use openspec-install first.
- Legacy files detected: Use
--forceto auto-cleanup, or follow the interactive prompts. - Tool not in list: Check the supported tools list for the correct ID.