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 commands (archive, unarchive, delete, submit --git).
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

observal registry mcp list --category developer-tools --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 (from git, recommended)

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

Without --git, opens interactive JSON paste (accepts harness config block, named config, bare config, or HTTP transport JSON). Press Enter on empty line to submit.

Skill

There are two delivery modes for skills:

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

observal registry skill submit --skill-md ./SKILL.md --git-url https://github.com/org/repo --git-ref main

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

observal registry skill submit --skill-md ./SKILL.md --delivery-mode registry_direct
observal registry skill submit --skill-md ./SKILL.md --script ./run.sh --delivery-mode registry_direct
observal registry skill submit --skill-md ./SKILL.md --script ./scripts/lint.sh --script ./scripts/test.sh --delivery-mode registry_direct

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 --from-file hook.json
observal registry hook submit   # interactive

With a script (inline or file):

observal registry hook submit --from-file hook.json --script ./pre-commit.sh

Optional: --script 'code', --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 --from-file prompt.json

Sandbox

observal registry sandbox submit --from-file sandbox.json

All types support --draft (save without review) and --submit NAME (submit 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'

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	Use --git, --draft, or interactive paste
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".