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
npx skills add sammcj/agentic-coding --skill openspec-bootstrap -a claude-codeWhat 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.yamlfrom 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 theleanschema. - Prepare OpenSpec from scratch: read
README,CLAUDE.md, andAGENTS.md, then check the YAML.
How to install openspec-bootstrap
1Skills CLI (Vercel)
npx skills add sammcj/agentic-coding --skill openspec-bootstrap -a claude-code2Manually: put the files in place
~/.claude/skills/openspec-bootstrap/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/openspec-bootstrap/
1Skills CLI (Vercel)
npx skills add sammcj/agentic-coding --skill openspec-bootstrap -a codex2Manually: put the files in place
.agents/skills/openspec-bootstrap/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add sammcj/agentic-coding --skill openspec-bootstrap -a cursor2Manually: put the files in place
.cursor/skills/openspec-bootstrap/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install sammcj/agentic-coding Skills/openspec-bootstrap/SKILL.md2Manually: put the files in place
.github/skills/openspec-bootstrap/SKILL.md1Skills CLI (Vercel)
npx skills add sammcj/agentic-coding --skill openspec-bootstrap -a gemini-cli2Platform CLI
gemini skills install https://github.com/sammcj/agentic-coding --path Skills/openspec-bootstrapManually: put the files in place
.devin/skills/openspec-bootstrap/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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