observal-registry

name	observal-registry
command	observal
description	Submit, browse, install, edit, archive, restore, transfer, and version MCPs, skills, hooks, prompts, and sandboxes in the Observal registry. Use when the user wants to submit a component, install one, edit a draft, publish a new version, or browse the component library.
version	2.0.0
owner	observal

Observal Registry: Component CRUD

Critical Rules

1. EXECUTE commands: run them in your shell. Set timeout to 60 seconds.
2. Pass --output json on list/show commands.
3. Pass --yes on destructive lifecycle commands (archive, unarchive) and MCP JSON submit when defaults are acceptable.
4. When in doubt about a flag, run <command> --help first.
5. --from-file does NOT exist on mcp submit: that flag is on mcp edit.

---

Procedure: Browse Registry

Use natural-language keywords with --search; do not require exact whole-query matches.

observal registry mcp list --category developer-tools --output json
observal registry skill list --search 'frontend design' --output json
observal registry skill list --task-type code-review --output json
observal registry hook list --event UserPromptSubmit --output json
observal registry prompt list --category coding --output json
observal registry sandbox list --runtime docker --output json

observal registry mcp my --output json
observal registry skill my --output json
observal registry prompt my --output json

observal registry mcp show NAME --output json
observal registry hook show NAME --output json

After list, use row numbers (1, 2, 3...) in subsequent commands. Add --interactive for fuzzy picker.

MCP categories: browser-automation, cloud-platforms, code-execution, communication, databases, developer-tools, devops, file-systems, finance, knowledge-memory, monitoring, multimedia, productivity, search, security, version-control, ai-ml, data-analytics, general

Skill task types: code-review, code-generation, testing, documentation, debugging, refactoring, deployment, security-audit, performance, general

---

Procedure: Submit Component

MCP

Paste the MCP JSON config. Optionally include --git so Observal clones the repo and detects local OCI setup for Dockerfile, Containerfile, or compose build:.

observal registry mcp submit --example
observal registry mcp submit --name my-mcp --category developer-tools --yes
observal registry mcp submit --git https://github.com/org/mcp-server --name my-mcp --category developer-tools --yes

The command still expects pasted JSON. If a local image must be built, follow the returned setup instructions, for example docker build -t name:latest .. Manual installs also print these setup instructions before the MCP can be used.

Skill

There are two delivery modes for skills:

Git-based (server validates SKILL.md from repo, recommended for open-source):

observal registry skill submit --example
observal registry skill submit --skill-md ./SKILL.md --git-url https://github.com/org/repo --git-ref main --name my-skill --description 'What it does' --task-type general

Registry direct (inline SKILL.md + optional script, no git repo needed):

observal registry skill submit --skill-md ./SKILL.md --delivery-mode registry_direct --name my-skill --description 'What it does' --task-type general --harness claude-code
observal registry skill submit --skill-md ./SKILL.md --script ./run.sh --delivery-mode registry_direct --name my-skill --description 'What it does' --task-type general

On install, registry_direct skills write <skill-name>/SKILL.md and <skill-name>/scripts/<filename> into the harness skills directory.

Decision guide:

• Use git-based when: you have a public repo, want CI on updates, need multi-file skills
• Use registry_direct when: the skill is self-contained, generated by insights, or has no external repo

Hook

observal registry hook submit --example
observal registry hook submit --name guard --description 'Guard prompts' --event UserPromptSubmit --handler-command './guard.sh' --execution-mode sync --timeout 10 --scope agent --harness claude-code
observal registry hook submit --from-file hook.json --script ./pre-commit.sh

Optional: --source-url URL --source-ref main, --requires dep1 --requires dep2. Timeout caps: blocking 30s, sync 10s, async 60s.

Hook events: Start, Stop, UserPromptSubmit, SubagentComplete, ToolResult, Error Execution modes: blocking (waits for completion), sync (waits, shorter timeout), async (fire and forget) Handler types: script (runs a shell script), http (calls a webhook URL)

Prompt

observal registry prompt submit --name frontend-brief --description 'Frontend design brief' --category general --template 'Design {{component}} accessibly'
observal registry prompt submit --from-file prompt.json

Sandbox

observal registry sandbox submit --example
observal registry sandbox submit --name node-runner --description 'Node sandbox' --runtime-type docker --image node:22-alpine --resource-limits '{"memory_mb":512}' --runtime-config '{}' --network-policy none --entrypoint node --harness claude-code
observal registry sandbox submit --name lxc-runner --description 'LXC sandbox' --runtime-type lxc --image images:ubuntu/22.04 --runtime-config '{"profile":"default"}' --network-policy none --entrypoint 'sh' --harness kiro
observal registry sandbox submit --from-file sandbox.json

All types support --example to print ready-to-edit example payloads, --draft to save without review, and --submit NAME to submit an existing draft.

---

Procedure: Install Component

observal registry mcp install NAME --harness kiro
observal registry mcp install NAME --harness claude-code --raw
observal registry mcp install NAME --harness cursor --version 2.1.0
observal registry skill install NAME --harness kiro --scope user
observal registry skill install NAME --harness claude-code --scope project
observal registry skill install NAME --harness claude-code --version 1.2.0
observal registry hook install NAME --harness kiro
observal registry hook install NAME --harness claude-code --platform darwin --dir .

Flags (all install commands):

• --harness (required): target harness
• --version <semver>: install a specific version instead of latest
• --raw: output JSON only (MCP)
• --scope user|project: install scope (skill)

---

Procedure: Edit Component

Warning: Editing an approved listing triggers a version bump flow. For draft/pending/rejected items, edits in place with an optimistic lock.

observal registry mcp edit NAME --from-file updates.json
observal registry mcp edit NAME --name new-name --description 'New desc'
observal registry skill edit NAME --from-file updates.json
observal registry hook edit NAME --version 1.2.0 --event Stop
observal registry prompt edit NAME --template 'New template body'
observal registry sandbox edit NAME --image python:3.12-slim

---

Procedure: Publish Component Version

observal registry version publish mcp NAME --version 1.2.0 --description 'What changed'
observal registry version publish skill NAME --version 0.3.0 --description 'New tasks'
observal registry version publish hook NAME --version 1.0.1 --description 'Bug fix'
observal registry version publish prompt NAME --version 2.0.0 --description 'Rewrite'
observal registry version publish sandbox NAME --version 1.1.0 --description 'New image' --extra '{"runtime_type":"docker","image":"python:3.12-slim","resource_limits":{"timeout":60}}'
observal registry version publish sandbox NAME --version 1.2.0 --description 'LXC profile' --extra '{"runtime_type":"lxc","image":"images:ubuntu/22.04","runtime_config":{"profile":"default"}}'

observal registry version list mcp NAME --output json

---

Procedure: Archive / Restore Component

observal registry mcp archive NAME --yes
observal registry skill archive NAME --yes
observal registry hook archive NAME --yes
observal registry prompt archive NAME --yes
observal registry sandbox archive NAME --yes

observal registry mcp unarchive NAME --yes
observal registry skill unarchive NAME --yes
observal registry mcp transfer-owner NAME @username -y
observal registry skill transfer-owner NAME @username -y

---

Procedure: Manage Co-Authors

Co-authors have equal access to the component owner (edit, publish, manage co-authors).

# List
observal registry mcp co-authors list <id-or-name>
observal registry skill co-authors list <id-or-name>

# Add
observal registry skill co-authors add <id-or-name> [e-mail]

# Remove
observal registry hook co-authors remove <id-or-name> <user-uuid>

Error Reference

Error	Fix
--from-file not on mcp submit	Paste JSON, optionally with --git, or use --draft
412 Edit lock held	Wait a few minutes, retry
Hook timeout	Caps: blocking 30s, sync 10s, async 60s

---

Output Contract

1. One sentence stating intent.
2. The exact command in a fenced code block.
3. The result: success / specific error.
4. The next action, or "done".