Skip to main content
Submit, browse, review, install, and safely update versioned skill folders, as well as Git-backed and historical single-file skills. See the complete skill folder workflow for the owner-to-reviewer-to-consumer journey and rollout requirements.

​
Commands

Every command that returns structured data supports table and JSON output. Archive, restore, and ownership transfer require the confirmation bypass in JSON mode.

​
Submit

Git-backed skills require a Git URL. Registry-direct skills can store SKILL.md, optional script resources, or a complete bounded folder with scripts, templates, binary assets and executable modes. Folder drafts are versioned; saving a draft does not submit it for review. Use an explicit fork or import-folder to create a successor to an approved release; never use submit --from-dir to silently overwrite one.
For a new complete folder, use observal registry skill submit --from-dir ./my-skill --name my-skill --description "My skill". To advance an approved listing, use fork (reviewed direct base) or import-folder (reviewed Git/historical direct base), then observal registry skill replace-files my-skill --version-id UUID --from-dir ./my-skill --revision OBSERVED_REVISION as needed. The folder workflow covers exact-base selection, sensitive/excluded file acknowledgments, review, and immutable releases. JSON mode never prompts; supply all required inputs explicitly. Valid task types are code-review, code-generation, testing, documentation, debugging, refactoring, deployment, security-audit, performance, and general.

​
List and show

Row numbers are scoped to the latest Skill list. Empty lists clear previous Skill row references.

​
Fork

The source listing and selected version must be approved; the copy begins as an independent draft. Inline registry_direct content is copied, but its validation flag resets for the normal submission path. Use the returned UUID to edit and submit without affecting the source. Only publicly approved forks appear in fork counts; private provenance is never exposed to viewers who lack source access.

​
Install

JSON output performs the installation unless no-write is selected. It reports write_performed and installed_path. Raw mode emits only the generated config and performs no write. Lockfile state is recorded only after the skill content is written successfully. A complete folder install requires the server’s default-off delivery gate, a compatible client, and a POSIX filesystem (Linux/macOS or WSL on its Linux filesystem). Native Windows managed folder installation, upgrades, backup restoration, and pinned Agent folder pulls are not supported; they fail closed rather than attempting an unsafe partial swap. The other CLI workflows and existing Git/single-file installations are not subject to this folder-swap restriction. Pin an approved --version for reproducible installs; omitting it follows the latest release. A managed folder is never replaced silently: first use --check-upgrade for a no-write preview, then --upgrade to verify every installed byte and mode, retain a private backup and update its receipt. --backup-root DIR must be private, ignored by Git when inside a worktree, outside skill discovery roots, and on the target filesystem. Cross-mode Git/single-file installs cannot erase existing folder receipts. The command fails if the harness lacks skill support, the source cannot be installed, the destination is unowned or locally edited, or installed state cannot be recorded. See verified updates and recovery before restoring a backup.

​
Edit

Edit-lock conflicts preserve conflict exit code 6. Invalid fields and files use the shared validation, not-found, permission, and unavailable categories.