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.

bash
observal registry mcp list --category developer-tools --output json
observal registry mcp list --namespace platform-tools --output json
observal registry skill list --namespace platform-tools --output json
observal registry skill list --team platform-tools --search 'frontend design' --output json
observal registry skill list --task-type code-review --harness claude-code --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. Team members see approved private teamspace items in the same lists. Use --team TEAM_HANDLE to list only what that teamspace owns, including its private items when you are a member. Direct references use TEAM_HANDLE/ITEM_SLUG. Skill search covers descriptions, task types, target agents, slash commands, source paths, delivery mode, and SKILL.md content.

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: Recommend Components For This User

Use when the user asks what to install, what is worth trying, or what they are missing. Ranked against the signed-in user's own sessions, so check here before browsing — it beats guessing keywords for list --search. --refresh recomputes the profile instead of using the 24h cache: slower, so only when recent work changed and results look stale.

bash
observal registry recommend --output json
observal registry recommend --limit 12 --type mcp --refresh --output json

| Field | Meaning | |-------|---------| | personalized | true = ranked against this user's sessions. false = popularity only | | profile_sessions | How many sessions the profile was built from | | topics | Dominant work areas detected (e.g. databases, frontend) | | items[].reason | Why this was picked. Quote it; do not invent a better reason | | items[].matched_on | The user's own terms that matched |

What you may claim: personalized: false → say plainly there is no session history yet and these are simply the most-used components; never present them as tailored. items: [] → say either nothing in the registry is visible to them or they already installed or dismissed it all; this is not an error, so do not report it as one. profile_sessions under ~5 → give the answer, and say the profile is thin.

bash
observal registry recommend dismiss skill NAMESPACE/SLUG
observal registry recommend dismiss mcp NAMESPACE/SLUG --action not_relevant
observal registry recommend dismiss hook NAMESPACE/SLUG --action installed

Dismissals are per-user and permanent until overwritten, so confirm before dismissing. A work profile is visible only to its owner: no flag or server route exposes another user's recommendations, so if asked, say it is unavailable rather than improvising a workaround.

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:.

bash
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
observal registry mcp submit --name internal-mcp --category developer-tools --team platform-tools --visibility team --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):

bash
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
observal registry skill submit --skill-md ./SKILL.md --git-url https://github.com/org/repo --name internal-skill --description 'Team skill' --task-type general --team platform-tools --visibility team

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

bash
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

bash
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

bash
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

bash
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

bash
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.

bash
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

bash
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

bash
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).

bash
# 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> user@example.com

# 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".