How do I install the Openspec Adopt skill?

Run npx skillmds@latest add connorgriffin/openspec-adopt in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Openspec Adopt safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Openspec Adopt?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Openspec Adopt free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Openspec Adopt?

ConnorGriffin (@connorgriffin) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Openspec Adopt by connorgriffin — Agent Skill

Name: Openspec Adopt
Author: ConnorGriffin

Openspec Adopt

Adopt OpenSpec in a repo that lacks it: scaffold the openspec/ layout, write baseline specs describing the system as it exists today (from code, docs, and git history), and deliver the whole thing as a documentation-only PR. One-time per repo. Trigger when the user asks to adopt openspec, add openspec to a repo, scaffold openspec, or write baseline specs. Invoked as /openspec-adopt <org/repo or path>.

ConnorGriffin a5f185f 2 files · 3.3 KB Updated Sep 17, 2026

File contents

openspec-adopt

One-time OpenSpec adoption for a repo. Scaffolds the documentation baseline before any change proposals reference it.

Procedure

Check it is actually absent. An existing openspec/ means this skill has nothing to do; point at it and stop.
Require the pinned CLI. OpenSpec is target-repository development tooling. Confirm that global @fission-ai/openspec@1.11.0 is available as openspec; if it is absent, stop visibly before changing the target repository. Do not substitute another version or a package-runner invocation.
Initialize the v1 tree. Run openspec init --tools none at the target repository root. If initialization fails, stop visibly; do not construct a replacement tree. This produces openspec/config.yaml, openspec/specs/, and openspec/changes/archive/ without editor integrations.
Record repository context and operations. Put the repo purpose, tech stack, conventions, and commit/PR standards in openspec/config.yaml's context: and rules:. Source them from README, CONTRIBUTING, CI workflows, and observed code idioms. Record the repository's chosen archive timing and landing path at operations.archive.guidance; this is a repository-local convention, not a rule supplied by this skill.
Choose spec domains. Select two to four domains that partition the system by behavior. Name them for what the system does, not for directories. Examples: authentication, persistence, deployment, external integration.
Write baseline specs. For each domain, specs/<domain>/spec.md describing current behavior and contracts: what exists, what invariants hold, what other systems depend on. Ground every claim in code you read or history you checked; a baseline is worthless if it guesses. Reference concrete files only where the file is the contract (a schema, a versions manifest).
Validate the result. Run openspec validate --all --strict at the target repository root and fix every reported issue; do not deliver a baseline the CLI rejects.
Deliver as a PR. Branch, commit the initialized tree and baselines, gh pr create, documentation-only, no code changes. The PR body states the baseline is a starting point and invites corrections from the people who know the system.

Rules

Never bundle adoption with a functional change; the baseline gets reviewed on its own.
Never write a baseline for a repo you have not read; if the repo is too large to ground properly, propose fewer domains and say what was left unspecified.
Specs describe behavior and contracts, not implementation walkthroughs.
Do not add generated agent integrations, openspec/AGENTS.md, or openspec/project.md.

---name: openspec-adoptdescription: Adopt OpenSpec in a repo that lacks it: scaffold the openspec/ layout, write baseline specs describing the system as it exists today (from code, docs, and git history), and deliver the whole thing as a documentation-only PR. One-time per repo. Trigger when the user asks to adopt openspec, add openspec to a repo, scaffold openspec, or write baseline specs. Invoked as /openspec-adopt <org/repo or path>.---# openspec-adoptOne-time OpenSpec adoption for a repo. Scaffolds the documentation baseline before any change proposals reference it.## Procedure1. **Check it is actually absent.** An existing `openspec/` means this skill has nothing to do; point at it and stop.2. **Require the pinned CLI.** OpenSpec is target-repository development tooling. Confirm that global `@fission-ai/openspec@1.11.0` is available as `openspec`; if it is absent, stop visibly before changing the target repository. Do not substitute another version or a package-runner invocation.3. **Initialize the v1 tree.** Run `openspec init --tools none` at the target repository root. If initialization fails, stop visibly; do not construct a replacement tree. This produces `openspec/config.yaml`, `openspec/specs/`, and `openspec/changes/archive/` without editor integrations.4. **Record repository context and operations.** Put the repo purpose, tech stack, conventions, and commit/PR standards in `openspec/config.yaml`'s `context:` and `rules:`. Source them from README, CONTRIBUTING, CI workflows, and observed code idioms. Record the repository's chosen archive timing and landing path at `operations.archive.guidance`; this is a repository-local convention, not a rule supplied by this skill.5. **Choose spec domains.** Select two to four domains that partition the system by behavior. Name them for what the system does, not for directories. Examples: authentication, persistence, deployment, external integration.6. **Write baseline specs.** For each domain, `specs/<domain>/spec.md` describing current behavior and contracts: what exists, what invariants hold, what other systems depend on. Ground every claim in code you read or history you checked; a baseline is worthless if it guesses. Reference concrete files only where the file is the contract (a schema, a versions manifest).7. **Validate the result.** Run `openspec validate --all --strict` at the target repository root and fix every reported issue; do not deliver a baseline the CLI rejects.8. **Deliver as a PR.** Branch, commit the initialized tree and baselines, `gh pr create`, documentation-only, no code changes. The PR body states the baseline is a starting point and invites corrections from the people who know the system.## Rules* Never bundle adoption with a functional change; the baseline gets reviewed on its own.* Never write a baseline for a repo you have not read; if the repo is too large to ground properly, propose fewer domains and say what was left unspecified.* Specs describe behavior and contracts, not implementation walkthroughs.* Do not add generated agent integrations, `openspec/AGENTS.md`, or `openspec/project.md`.

Frequently asked questions