Skip to main content
skill CX Codex

openspec-bootstrap — Claude Code skill: OpenSpec setup

openspec-bootstrap sets up OpenSpec in a repository by preparing its schema and config. Use it for a first-time setup or edits to openspec/config.yaml.

Apache-2.0 ★ 173 updated 2026-10-30

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add sammcj/agentic-coding --skill openspec-bootstrap -a claude-code
Open on GitHub

What openspec-bootstrap does

This skill guides an OpenSpec setup from repository inspection to validation. If openspec/ is absent, it runs openspec init --tools <the agents this repo uses>, reads project documentation, and copies the lean schema into openspec/schemas/lean/. It then creates or updates openspec/config.yaml with project-specific context.

The workflow checks for leftover placeholders, runs openspec schema validate lean, and parses the YAML with Python. Configuration rules should point agents to project context rather than prescribe internal implementation details. An existing config with real repository rules must be merged, not casually replaced, so those facts remain available. Unfilled placeholders are turned into questions for the user.

What it helps with

  • set up OpenSpec in a new repository
  • copy the openspec/schemas/lean/ schema
  • fill in openspec/config.yaml from project docs
  • validate the schema and YAML
  • turn unresolved placeholders into user questions

Example prompts for the agent

  • Set up OpenSpec in this repository with openspec-bootstrap.
  • Review openspec/config.yaml, merge its repository rules with the template, and validate the lean schema.
  • Prepare OpenSpec from scratch: read README, CLAUDE.md, and AGENTS.md, then check the YAML.

How to install openspec-bootstrap

1Skills CLI (Vercel)

npx skills add sammcj/agentic-coding --skill openspec-bootstrap -a claude-code

2Manually: put the files in place

~/.claude/skills/openspec-bootstrap/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/openspec-bootstrap/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about openspec-bootstrap

How do I install openspec-bootstrap in Claude Code?

Run npx skills add sammcj/agentic-coding --skill openspec-bootstrap -a claude-code, then use ~/.claude/skills/openspec-bootstrap/SKILL.md.

What does openspec-bootstrap do?

It prepares OpenSpec for a repository by setting up the schema and openspec/config.yaml, checking the result, and surfacing unfinished placeholders as questions.

How does it handle an existing openspec/config.yaml?

A config with real repository rules is merged with the template. Repository facts stay in place, while rules that prescribe internal code details are removed.

Source text

SKILL.md · Apache-2.0
---
name: openspec-bootstrap
description: Use when setting up OpenSpec in a repo for the first time, or editing a repo's `openspec/config.yaml` or project schema
metadata:
  version: 2026-10-30
---

The config steers every artifact agents write later. Its main job is keeping a change's artifacts at the outcome level. Artifacts that prescribe implementation detail go stale as soon as the implementation drifts, and agents then spend effort resyncing them. The template's `context` states that principle, with contracts as the one exception.

## Workflow

1. Create a task per step below, phrased with its completion criterion, then work them to completion.
2. If `openspec/` is missing, run `openspec init --tools <the agents this repo uses>`. Done when `openspec/config.yaml` exists.
3. Read the README, CLAUDE.md/AGENTS.md, the build entrypoint (Makefile or similar) and any planning or decision docs. Done when you can name what the project is, its hard constraints and where decisions live.
4. Copy `assets/schemas/lean/` from this skill's directory to the project as `openspec/schemas/lean/`. It is `spec-driven` trimmed to outcome-level sections, with each fact held in one artifact. Done when `openspec schema validate lean` passes.
5. Copy `assets/config.yaml` from this skill's directory to the project as `openspec/config.yaml`, then fill it in.
  - Keep it short. Include only what agents must take into account when working with OpenSpec in this project.
  - Add a repo-specific rule only when the repo's docs show it needs one.
  - If a config with real content already exists, merge into it instead: keep its repo-specific facts and replace rules that prescribe internal code.
  - Delete any placeholder line you can't fill and note it for step 8.
  - Done when `rg -n '<[^>]+>' openspec/config.yaml` finds nothing.
6. Check every rule you wrote against the template's `context` and the `lean` schema's instructions. Remove any rule that tells future agents to prescribe implementation detail, restates a schema instruction, or adds a section to every change.
7. Confirm the YAML parses: `python3 -c 'import yaml,sys; yaml.safe_load(open(sys.argv[1]))' openspec/config.yaml`.
8. Report the deleted placeholders to the user as questions rather than guessing values.

## Gotchas

- Rules are appended to the schema's artifact instructions (`openspec/schemas/lean/schema.yaml`). Those already cover spec scope, user decisions, per-task verification, per-group tests and size targets. Write rules only for what the repo needs beyond them. A rule that contradicts the schema gets half-followed; edit the project's schema copy instead.
- Every rule tends to add a section to every change. Prefer limits ("only when ...") to requests ("include ...").
- Size targets in lines don't bind: agents write long lines. Use words.
- `lean` is a fork of OpenSpec 1.15.0's `spec-driven`. After an OpenSpec upgrade, compare it with `openspec schema fork spec-driven` output and carry over upstream fixes. `lean` keeps prose unwrapped while upstream wraps it, so compare with `git diff --no-index --word-diff`.
- `context` should point to files (CLAUDE.md, decision docs) rather than copying their commands or facts, which then drift.
- `operations` supports only `apply` and `archive`. OpenSpec only warns about other keys at instruction time, so a YAML parse misses them.
- Explore reads only `context` and `rules`. Behaviour wanted outside a single artifact or apply/archive goes in `context`.
- Archive blocks on unchecked task boxes, so the template's Human checks rule uses plain bullets. Keep that wording when merging into an existing config.
- Sub-agents never read the config. Rules they must follow go in `apply` guidance as something the main agent puts in each brief.
- Changes already in flight keep their current artifacts. The new rules apply to new changes.

© sammcj · Apache-2.0 · sammcj/agentic-coding

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set73

The whole set →
json-schema-lookup json-schema-lookup — a skill that points Claude at the SchemaStore catalog so it can validate config files and look up allowed options. CX Codex +1 ★ 173repo stars deferred-task-execution deferred-task-execution delays command execution in Claude Code for a specific duration or until a chosen time. Handy when builds or scripts need to wait. CX Codex +1 ★ 173repo stars compression-editor compression-editor is a Claude Code subagent that shortens prose, instructions, skills, and docs without losing meaning. It skips source code and summarisation. CX Codex ★ 173repo stars explain Explains code, systems, and algorithms using terminal ASCII diagrams or standalone interactive HTML step-through pages. CX Codex +1 ★ 173repo stars self-review self-review — a skill that critically reviews your recent changes and fixes what it finds. Small edits it handles itself; larger ones go to a sub-agent. CX Codex +1 ★ 173repo stars writing-fragments The writing-fragments skill interviews you about a writing topic and saves promising bits in one Markdown file. Use it to gather ideas before deciding how an article should be structured. CX Codex +1 ★ 173repo stars code-simplification code-simplification is a Claude Code skill that spots hard-to-follow code and suggests refactors. It comes into play during code review or when reducing unnecessary abstractions. CX Codex +1 ★ 173repo stars domain-model Skill to actively shape your domain model: challenges terms against the glossary, stress-tests boundaries with scenarios, records glossary and decisions in CONTEXT.md and ADRs. CX Codex +1 ★ 173repo stars

Project sponsors

Companies that keep this analytics open