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.

References

国内适配

支持中文文档和中文注释
示例代码兼容国内开发环境
提供中文 FAQ 和常见问题解答

能力边界

✅ 适用场景

当你需要使用此技能对应的技术栈时
当项目需要遵循最佳实践时
当需要快速上手或深入理解核心概念时

⚠️ 需要注意

复杂业务逻辑需要结合具体场景调整
性能优化需要根据实际数据量评估

❌ 不适用场景

不相关的技术栈或框架
需要完全自定义的特殊场景

使用流程

Step 1: 环境准备

确保开发环境已安装必要的依赖和工具。

Step 2: 配置初始化

根据项目需求进行基础配置。

Step 3: 核心功能使用

按照示例代码实现核心功能。

Step 4: 测试验证

运行测试确保功能正常。

Step 5: 部署上线

完成开发后进行部署和监控。