Skills registry

Skills are the reusable instructions that AI agents invoke to perform well-defined tasks in this repo — propose a change, archive a change, run explore mode, and so on. They live in one canonical location and are fanned out to each supported provider by a small sync script.

The goal is provider-agnostic authoring. You write a skill once under .ai/skills/, register it in .ai/manifest.yaml, run pnpm ai:sync, and the same skill becomes available in Claude Code, Codex, and Cursor — each with the filename conventions and frontmatter that provider expects.

Layout

.ai/
├── manifest.yaml            # registry: which skills and commands are published, and to which providers
├── skills/                  # canonical skill sources (one directory per skill)
│   └── <skill-name>/
│       └── skill.md
├── commands/                # optional slash-command wrappers (opsx/propose, opsx/apply, …)
│   └── opsx/
│       └── <command>.md
└── providers/               # per-provider adapter configs
    ├── claude/adapter.yaml
    ├── codex/adapter.yaml
    └── cursor/adapter.yaml

A skill source is just a markdown file with YAML frontmatter (name, description, and optional metadata) followed by the instructions the agent should follow. The sync script reads the manifest, looks up the source, applies the provider's adapter rules (filename case, frontmatter transform, output directory), and writes the result into .claude/, .codex/, or .cursor/ as appropriate.

The manifest

.ai/manifest.yaml is the single source of truth for which skills exist and where they publish. A minimal entry looks like:

1
version: 1
2
 
3
skills:
4
  openspec-propose:
5
    source: skills/openspec-propose/skill.md
6
    providers: [claude, codex, cursor]
7
 
8
commands:
9
  opsx/propose:
10
    source: commands/opsx/propose.md
11
    providers: [claude, cursor]

Three things to know:

• source is a path relative to .ai/. It's always the canonical markdown file.
• providers is the fan-out list. Every provider in the list gets a copy of the skill through its adapter.
• Commands are separate from skills. Slash commands (like opsx:propose) are thin wrappers that invoke a skill. Codex doesn't support slash commands, so command entries typically list [claude, cursor] while their underlying skills list all three.

The provider adapters

Each provider has an adapter.yaml under .ai/providers/<name>/ that tells the sync script where to put files and how to transform them. The shape is deliberately small:

1
outputDir: .claude
2
 
3
mappings:
4
  skills:
5
    target: "skills/{name}/SKILL.md"
6
    transform: uppercase-filename
7
 
8
  commands:
9
    target: "commands/{path}.md"
10
    frontmatter: passthrough

For Claude, a skill at .ai/skills/openspec-propose/skill.md becomes .claude/skills/openspec-propose/SKILL.md (uppercase filename — Claude's convention). For Cursor and Codex, the same source becomes the file those tools expect. The sync script does the copy and the transform; the adapter config captures every provider-specific quirk in one place.

The sync script

pnpm ai:sync runs scripts/ai-sync.mjs. It:

1. Reads .ai/manifest.yaml.
2. For every skills: entry, loads the source markdown and the listed providers' adapter configs.
3. For every (skill, provider) pair, writes the transformed file to the provider's outputDir.
4. Does the same for commands: entries.

Use pnpm ai:sync --check in CI to verify the generated output is up to date with the sources. The opsx:archive skill runs this check before finalising a change, so a forgotten sync won't sneak into an archive.

Registered skills

At time of writing, the canonical skill set is:

All five skills are published to [claude, codex, cursor] via the manifest. The slash-command wrappers opsx:propose, opsx:apply, opsx:explore, and opsx:archive are published to [claude, cursor] (Codex invokes the underlying skill directly).

Authoring a new skill

What's next?

• Read the Openspec workflow page to see the skills in context.
• Read the Surfaces inventory page to understand how proposals verify coverage.
• Browse .ai/skills/ in the repo to see the real skill sources.