OpenSpec Config Skill
Manage OpenSpec configuration at two levels: project config (openspec/config.yaml) for project-specific context and rules, and global CLI config (openspec config subcommands) for user-level settings.
When to Use
- The user wants to add project context to improve AI artifact quality.
- Setting per-artifact rules (e.g. "specs must use Given/When/Then").
- Changing the default schema for the project.
- Managing global CLI settings (telemetry, editor, etc.).
Prerequisites
- OpenSpec initialized in the project (see openspec-initial).
Project Configuration
openspec/config.yaml
# Default schema for new changes
schema: spec-driven
# Project context injected into all artifact instructions
context: |
Tech stack: TypeScript, React, Node.js
API conventions: RESTful, JSON responses
Testing: Vitest for unit tests, Playwright for e2e
Style: ESLint with Prettier, strict TypeScript
# Per-artifact rules
rules:
proposal:
- Include rollback plan
- Identify affected teams
specs:
- Use Given/When/Then format for scenarios
design:
- Include sequence diagrams for complex flows
Config Fields
| Field | Type | Description |
|---|
schema | string | Default schema for new changes (e.g. spec-driven) |
context | string | Project context injected into all artifact instructions (max 50KB) |
rules | object | Per-artifact rules, keyed by artifact ID |
How It Works
- Schema precedence (highest to lowest): CLI flag -> change metadata -> project config -> default (
spec-driven). - Context injection: Prepended to every artifact's instructions in
<project-context> tags. - Rules injection: Only for matching artifacts, in
<project-rules> tags, after context.
Artifact IDs (spec-driven schema)
proposal — Change proposalspecs — Specificationsdesign — Technical designtasks — Implementation tasks
Global CLI Configuration
openspec config list # Show all settings
openspec config get <key> # Get a value
openspec config set <key> <value> # Set a value
openspec config unset <key> # Remove a key
openspec config reset --all --yes # Reset to defaults
openspec config edit # Open in $EDITOR
openspec config path # Show config file location
Common Settings
| Setting | Example |
|---|
| Disable telemetry | openspec config set telemetry.enabled false |
| Set user name | openspec config set user.name "My Name" --string |
Outputs
openspec/config.yaml with project context and rules.- Improved AI artifact quality through context injection.
Next Steps
- Start working with openspec-new or openspec-explore.
- Create a custom schema with openspec-schema and set it as default in config.
Troubleshooting
- "Unknown artifact ID in rules": Check artifact IDs match your schema; run
openspec schemas --json. - Config not applied: Ensure file is at
openspec/config.yaml (not .yml); check YAML syntax. - Context too large: Limit is 50KB; summarize or link to external docs.
References
