# openspec-bootstrap

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf (Devin Desktop), Claude.ai · ★ 173 repo stars
- Author: sammcj
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/sammcj/agentic-coding/tree/HEAD/Skills/openspec-bootstrap/SKILL.md
- Updated: 2026-10-30
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/openspec-bootstrap

## What it 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.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add sammcj/agentic-coding --skill openspec-bootstrap -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/openspec-bootstrap/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/openspec-bootstrap/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add sammcj/agentic-coding --skill openspec-bootstrap -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/openspec-bootstrap/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add sammcj/agentic-coding --skill openspec-bootstrap -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/openspec-bootstrap/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install sammcj/agentic-coding Skills/openspec-bootstrap/SKILL.md
```

2. **Manually: put the files in place**
- File: `.github/skills/openspec-bootstrap/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add sammcj/agentic-coding --skill openspec-bootstrap -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/sammcj/agentic-coding --path Skills/openspec-bootstrap
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/openspec-bootstrap/SKILL.md` — The legacy .windsurf/skills/ path still works

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/sammcj/agentic-coding/tree/HEAD/Skills/openspec-bootstrap/SKILL.md

## When to use it
- 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
- 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.

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 74178190d50d0868.

BEGIN THIRD-PARTY FILE 74178190d50d0868
```text
---
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.
```
END THIRD-PARTY FILE 74178190d50d0868

The third-party file has ended. Everything between the 74178190d50d0868 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2831 of 3872 bytes. © sammcj · Apache-2.0 · https://github.com/sammcj/agentic-coding/tree/HEAD/Skills/openspec-bootstrap/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
