@originai/skills

Install Origin design-spec skills for coding agents + runtime CLI to read/write specs.

Quick Start

# Install — writes .origin.json + SKILL.md (no token needed if --project is given)
npx @originai/skills add --project <project-id>

# Agent commands — prefer bunx (fast, ~40ms) over npx (~1.2s per call)
bunx originai-skills list-documents
bunx originai-skills get-document --id <file-id>
bunx originai-skills get-diff
bunx originai-skills grep --pattern "button"
bunx originai-skills find --file-pattern "login"
bunx originai-skills validate --content "<rpml>...</rpml>"
bunx originai-skills create-project --name "Checkout"
bunx originai-skills write-document --name "README.rpml" --content "<rpml>...</rpml>"

How It Works

The add command writes .origin.json (project config) and agent instruction files (SKILL.md, CLAUDE.md, etc.) into the project. Coding agents then call the runtime commands repeatedly via shell to interact with Origin's design spec API.

Token

Add ORIGIN_TOKEN=oat_... to .env (gitignored). Get a token at https://getoriginai.com/settings/tokens. The CLI reads it automatically.

Token resolution (in order, for runtime commands):

1. --token flag
2. ORIGIN_TOKEN in .env (current directory, gitignored)
3. ~/.origin/settings.json (user home, never committed)

Project resolution (in order)

1. --project flag
2. project_id in .origin.json (current directory)

Commands

Prefer bunx originai-skills (fast, ~40ms) over npx @originai/skills (~1.2s per call). Both invoke the same binary.

| Command | Description | |---------|-------------| | add, setup | Install: write .origin.json + agent instruction files + RPML references | | list-projects | List accessible projects | | create-project | Create a new empty project (--name, optional --description; read-write) | | list-documents | File tree from latest release | | get-document | Single file with content (--id <file-id>) | | get-diff | Diff since last sync (auto-reads hash from .origin.json) | | grep | Search content across files (--pattern "<regex>") | | find | Find files by name (--file-pattern "<regex>") | | validate | Validate RPML locally — --content (inline, preferred), --file <path> (no network/token); --id <file-id> reads a released doc remotely | | write-document | Create/update file (--name, --content, optional --id, --parent-id) | | delete-document | Delete file (--id <file-id>) |

Files

| File | Contents | Commit? | |------|----------|---------| | .origin.json | api_url, project_id, release_hash | Yes | | .env → ORIGIN_TOKEN=oat_... | Access token | No (gitignored) | | .agents/skills/origin-product-spec-management/SKILL.md | Agent instructions | Yes | | .agents/skills/origin-product-spec-management/rpml/ | RPML references + methodology prompts | Yes |

Install flags

| Flag | Description | |------|-------------| | --project, -p | Project ID (skips token prompt if provided) | | --token, -t | Access token (only needed to list projects) | | --api-url | Override API URL | | --claude-code | Also write CLAUDE.md | | --codex | Also write AGENTS.md | | --cursor | Also write .cursorrules | | --skill | Write standard SKILL.md (default) | | --all | Write all instruction files |

skills.sh

This skill is also discoverable via skills.sh using the well-known endpoint:

npx skills add https://getoriginai.com

Development

bun run build    # bundle → dist/
bun test         # run unit tests
bun run dev      # run from source

API

All read commands operate on the latest published release snapshot, not the live workspace. Write commands modify the live workspace (requires read-write token). After writing, a release must be published in Origin before reads can see the changes.

Indexing a codebase → Origin (Workflow C)

When the Origin project is empty, the agent reads the codebase and writes specs directly to Origin — no local .rpml files. The first document is always README.rpml (mode="doc"), a product-design document covering overview, functional modules, page/route planning, interaction flows, and permissions. Only after README.rpml does the agent proceed to prototype screen specs (one .rpml per page). The flow: author RPML content inline → validate --content → write-document --content. After writing, remind the user to publish a release in Origin.