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 proposal
specs — Specifications
design — Technical design
tasks — 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.

openspec-config