/observal-registry

# SPDX-FileCopyrightText: 2026 Hemalatha Madeswaran <hemalathamadeswaran@gmail.com>
# SPDX-License-Identifier: Apache-2.0
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, and get components recommended for the current user. Use when the user wants to submit a component, install one, edit a draft, publish a new version, browse the component library, or asks what they should install or are missing.
version: 2.1.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 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.

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.

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

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

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