teachingai/openspec-schema

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

1. Project: openspec/schemas/<name>/ (local, version controlled)
2. User: ~/.local/share/openspec/schemas/<name>/ (global)
3. 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

• OpenSpec CLI: schema commands
• OpenSpec Concepts: Schemas
• OpenSpec Customization