openspec-schema

Q: How do I install openspec-schema?

Run npx skills add https://github.com/full-stack-skills/openspec-skills --skill openspec-schema in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/openspec-schema/ (personal) or .claude/skills/openspec-schema/ (project).

by full-stack-skillsProductivity & Automation

Create and manage custom workflow schemas using openspec schema init/fork/validate/which. Use when the user says "create a custom workflow", "custom schema", "fork a schema", or wants to define their own artifact types and dependencies.

Installs: 102
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/full-stack-skills/openspec-skills --skill openspec-schema

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads openspec-schema automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

OpenSpec Schema Skill

Use openspec schema subcommands to create and manage custom workflow schemas. Schemas define what artifacts exist and their dependencies. The default spec-driven schema provides proposal -> specs -> design -> tasks, but custom schemas allow different workflows.

When to Use

The user wants a custom workflow (e.g. research-first, rapid iteration).
The user says "create a schema", "custom workflow", "fork the spec-driven schema".
Debugging schema resolution (openspec schema which).
Validating a custom schema's structure.

Prerequisites

OpenSpec CLI installed (see openspec-install).

Workflow

Create a new schema from scratch

openspec schema init my-workflow
# Interactive: prompts for description, artifacts, default
# Non-interactive:
openspec schema init rapid --description "Rapid iteration" --artifacts "proposal,tasks" --default

Creates openspec/schemas/my-workflow/ with schema.yaml and templates/.

Fork an existing schema

openspec schema fork spec-driven my-workflow

Copies the spec-driven schema for customization.

Validate a schema

openspec schema validate my-workflow
# Or validate all:
openspec schema validate

Check schema resolution

openspec schema which spec-driven
# Shows: package, project, or user source
openspec schema which --all

Schema Structure

openspec/schemas/<name>/
├── schema.yaml       # Artifact definitions and dependencies
└── templates/
    ├── proposal.md   # Template for each artifact
    ├── specs.md
    ├── design.md
    └── tasks.md

Example schema.yaml

name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []
  - id: proposal
    generates: proposal.md
    requires: [research]
  - id: tasks
    generates: tasks.md
    requires: [proposal]

Schema Precedence

Project: openspec/schemas/<name>/ (local, version controlled)
User: ~/.local/share/openspec/schemas/<name>/ (global)
Package: Built-in schemas (e.g. spec-driven)

Outputs

Custom schema in openspec/schemas/<name>/ with schema.yaml and templates.

Next Steps

Use the schema with openspec-new: /opsx:new my-change --schema my-workflow.
Or set as default in openspec-config (openspec/config.yaml).

Troubleshooting

"Schema not found": Check openspec schemas for available schemas; check openspec schema which <name> for resolution.
Validation errors: Run openspec schema validate <name> --verbose for details.
Unknown artifact IDs in rules: Check openspec schemas --json for artifact IDs per schema.

References

FAQ

What does the openspec-schema skill do?

How do I install openspec-schema?

Run npx skills add https://github.com/full-stack-skills/openspec-skills --skill openspec-schema in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/openspec-schema/ (personal) or .claude/skills/openspec-schema/ (project).

Which AI agents can use openspec-schema?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is openspec-schema safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains openspec-schema?

It is published by full-stack-skills in full-stack-skills/openspec-skills. It has 102 recorded installs.