# Openspec Config

> Configure OpenSpec project settings and global CLI configuration using `openspec/config.yaml` and `openspec config` commands. Use when the user says "configure OpenSpec", "project config", "add project context", or wants to set per-artifact rules.

- Skill: `full-stack-skills/openspec-config` (Agent Skill)
- Install (CLI): `npx skillmds@latest add full-stack-skills/openspec-config`
- Raw SKILL.md: https://api.skillmd.com/api/skills/full-stack-skills/openspec-config/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: full-stack-skills (https://skillmd.com/u/full-stack-skills)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/full-stack-skills/openspec-config

---


# 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

```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

```bash
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

- [OpenSpec CLI: config](https://github.com/Fission-AI/OpenSpec/blob/main/docs/cli.md)
- [OpenSpec OPSX: Project Configuration](https://github.com/Fission-AI/OpenSpec/blob/main/docs/opsx.md)

## 国内适配

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

## 能力边界

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

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

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

## 使用流程

### Step 1: 环境准备
确保开发环境已安装必要的依赖和工具。

### Step 2: 配置初始化
根据项目需求进行基础配置。

### Step 3: 核心功能使用
按照示例代码实现核心功能。

### Step 4: 测试验证
运行测试确保功能正常。

### Step 5: 部署上线
完成开发后进行部署和监控。