apus skills

Inspect local skills, search ClawHub, install skills from ClawHub/Git/local directories, verify ClawHub skills, and update ClawHub-tracked installs.

Use apus plugins for plugin packages. The standalone ClawHub CLI handles publishing, registry maintenance, and removing ClawHub skills.

Related:

• Skills system: Skills
• Skill authoring: Creating skills
• Skill Workshop: Skill Workshop
• Skills config: Skills config

Commands

apus skills search "calendar"
apus skills search --limit 20 --json
apus skills install @owner/<slug>
apus skills install @owner/<slug> --version <version>
apus skills install skills-sh:<owner>/<repo>/<slug>
apus skills install git:owner/repo
apus skills install git:owner/repo@main
apus skills install ./path/to/skill --as custom-name
apus skills install @owner/<slug> --force
apus skills install @owner/<slug> --force-install
apus skills install @owner/<slug> --acknowledge-install-policy-warning
apus skills install @owner/<slug> --agent <id>
apus skills install @owner/<slug> --global
apus skills update @owner/<slug>
apus skills update @owner/<slug> --force
apus skills update @owner/<slug> --force-install
apus skills update @owner/<slug> --acknowledge-install-policy-warning
apus skills update @owner/<slug> --global
apus skills update --all
apus skills update --all --agent <id>
apus skills update --all --global
apus skills verify @owner/<slug>
apus skills verify @owner/<slug> --json
apus skills verify @owner/<slug> --version <version>
apus skills verify @owner/<slug> --tag <tag>
apus skills verify @owner/<slug> --card
apus skills verify @owner/<slug> --global
apus skills list
apus skills list --eligible
apus skills list --json
apus skills list --verbose
apus skills list --agent <id>
apus skills info <name>
apus skills info <name> --json
apus skills info <name> --agent <id>
apus skills check
apus skills check --agent <id>
apus skills check --json
apus skills workshop list
apus skills workshop changes --limit 20
apus skills workshop show <name>
apus skills workshop archive <name> --reason "Superseded"
apus skills workshop restore <name>

search, update, and verify use ClawHub directly. install @owner/<slug> installs a native ClawHub skill. install skills-sh:<owner>/<repo>/<slug> asks ClawHub to resolve an external listing to its exact synchronized GitHub commit; Apus does not download from skills.sh. These entries are shown as Not scanned by ClawHub, and that trust state is preserved through updates and verification. Claimed or ClawHub-scanned skills use @owner/<slug>. install git:owner/repo[@ref] clones an unmanaged Git skill, and install ./path copies a local skill directory. Both fail before copying when the root SKILL.md is not loadable under the same content rules: frontmatter with a description, within skills.limits.maxSkillFileBytes. A hardlinked source file is copied as a new file, so that link does not fail the check. By default, install, update, and verify target the active workspace skills/ directory; with --global, they target the shared managed skills directory. list/info/check and bare apus skills request the selected Gateway's authoritative skill inventory. A configured remote Gateway or an explicit APUS_GATEWAY_URL never falls back to client-local skills: missing URLs, connection failures, and authentication errors remain visible. Only an implicitly selected local Gateway can fall back to local inventory when it is unavailable. Workspace-backed commands resolve the target workspace from --agent <id>, then the current working directory when it is inside a configured agent workspace, then the default agent.

Search results add v only to numeric version labels, preserving existing prefixes and build names. JSON output keeps the registry's original version values.

The skills table renders horizontal tabs as single spaces so descriptions stay aligned with the neighboring columns. JSON output preserves tabs and line endings in descriptions and paths as escaped characters.

info resolves an exact skill name before a metadata key. Key, case-insensitive, and separator-normalized matches must identify one skill; ambiguous selectors fail instead of choosing discovery order.

check separates inventory, readiness, and visibility:

• Inventory means Apus found the skill in a configured root or bundled source and can report its status.
• Readiness means the skill's declared prerequisites are satisfied for the selected Gateway or node, so it is eligible to run.
• Visibility means an eligible skill is exposed to the selected agent's prompt, picker, or command surface after agent filters and invocation flags are applied.

check reports missing prerequisites independently of agent exclusion: a skill excluded by the agent allowlist can also appear under Missing requirements. Disabled skills and skills blocked by the bundled allowlist keep their separate readiness categories. Treat a listed skill with missing requirements as present in inventory but not currently eligible or visible to the agent; install or configure the reported prerequisite before expecting the model to use it successfully.

Workshop commands preserve the same target boundary. They never read or mutate client-local state after an explicitly selected Gateway fails; intentional offline behavior remains available only for an implicitly selected local Gateway.

Git and local directory installs expect SKILL.md at the source root. The install slug comes from SKILL.md frontmatter name when it is valid, then the source directory or repository name; use --as <slug> to override it. --version is ClawHub-only. Skill installs do not support npm package specs or zip/archive paths, and apus skills update updates ClawHub-tracked installs only.

Gateway-backed skill dependency installs triggered from onboarding or Skills settings use the separate skills.install request path instead.

When security.installPolicy returns warn in an interactive terminal, Apus prints the reason and findings, then asks type: '<skill>' to install anyway (or update anyway). If the fully rendered review exceeds 4,000 characters, Apus fails closed before prompting; reduce or coalesce the policy output first. A matching answer evaluates the staged skill again before continuing. Declined and non-interactive direct CLI commands stop before commit; after review, --acknowledge-install-policy-warning is the explicit noninteractive approval for every warning in that command invocation. Every approved warning is re-evaluated before continuing. Automatic and managed skill installs cannot use that flag themselves. Use an equivalent direct CLI command when one exists; otherwise, change security.installPolicy to return allow for the reviewed request, then retry the managed flow. Neither --force nor the acknowledgement overrides block or a policy failure.

Notes:

On servers supporting full scanner reports, verification JSON includes security.scannerReports.aig (the full upstream SARIF report) and security.scannerReports.skillspector (the full upstream JSON report) when ClawHub has retained them. Nested scanner fields pass through unchanged, including coverage and incomplete-analysis details. A report is null when unavailable, including older scans whose full output was not retained; summaries are not substituted. Older servers may omit security.scannerReports entirely. verify reads the stored scan and does not start another scan. Verification responses can be up to 64 MiB; larger responses fail explicitly without printing partial reports. Other ClawHub JSON requests retain their 16 MiB limit.

Release trust

Community ClawHub skill installs and updates check trust before downloading. Versioned community archive releases use exact-release trust metadata. Resolver-backed GitHub skills rely on ClawHub's install resolver to enforce scan and force-install policy before it returns a pinned commit; use --force-install to install a pending GitHub-backed skill before that scan completes. Malicious or blocked community releases are refused. Review outcomes print the exact ClawHub audit overview and details link, then continue. Official ClawHub skill publishers and bundled Apus skill sources bypass this release-trust check.

Remove a ClawHub skill

Use the standalone ClawHub CLI to remove a ClawHub-tracked skill. If the CLI is not installed, install it explicitly first:

npm i -g clawhub
clawhub uninstall @owner/my-skill

The CLI asks for confirmation before deleting the skill directory and its .clawhub/lock.json entry. Use the installed skill's owner-qualified name or bare slug, not its original skills-sh: reference.

Select the same root where the skill was installed: the agent workspace for an agent-specific skill, or the Apus state directory for a shared skill installed with --global:

clawhub --workdir /path/to/agent-workspace uninstall @owner/my-skill
clawhub --workdir ~/.apus uninstall @owner/my-skill

If APUS_STATE_DIR is set, use that configured state directory for shared skills instead:

clawhub --workdir "$APUS_STATE_DIR" uninstall @owner/my-skill

The default skills watcher picks up the removal on the next agent turn. If watching is disabled, start a new session.

Personal skill library

apus skills library manages the identified caller's skills on the selected Gateway. It uses the same owner-aware service as the Control UI and agent workflow; it never writes the library database or revision directories on the CLI host.

apus skills library --help

List your library:

apus skills library list --scope mine --json

Create a private skill from a directory containing SKILL.md:

apus skills library create ./my-skill --slug my-skill

Read its stable ID and current revision before editing:

apus skills library read <skill-id> --json

Update only the instructions while preserving supporting files:

apus skills library update <skill-id> ./SKILL.md --expected-revision <revision-hash>

A directory input replaces the complete bundle. A single SKILL.md input preserves the current supporting files; repeat --delete-file <relative-path> to remove files explicitly. Updates compare the revision that was read; a conflict requires reviewing the newer content, not a force overwrite. Supporting files are part of the revision, including binary assets and executable flags.

Import a ZIP privately:

apus skills library import ./my-skill.zip --slug my-skill

Import a ClawHub skill without publishing your library:

apus skills library import @owner/<slug> --clawhub --slug my-skill

--version <version> selects a ClawHub version and requires --clawhub. share, unshare, transfer, enable, disable, remove, and rollback take <skill-id> --expected-revision <hash>. Rollback also requires --revision <retained-hash>.

Attach an exact revision to an existing session:

apus skills library attach --session <session-key> --skill-id <skill-id> --revision <revision-hash>

detach takes the same session and skill ID. Refresh one selected skill:

apus skills library refresh --session <session-key> --skill-id <skill-id>

Omitting --skill-id refreshes all selected skills and requires current library access to each one. It never replaces the selection with the current caller's library. Each operation reports its effect on the next turn.

Use list --session <session-key> to inspect selected revisions and the skills you can attach, without changing the session. read --session <session-key> also requires --revision <hash> and reads only that exact selected revision; it does not expose other private revisions or grant permission to edit them.

Personal operations require an authenticated Gateway profile. The Control UI on a single-user Gateway uses a durable owner profile, but ephemeral CLI connections do not inherit it. A CLI shared token or password alone still has no personal profile; use the existing workspace commands in that case. An explicitly selected remote Gateway never falls back to a client-local personal library.

Sharing makes a skill available to teammates but does not grant edit access. Transfer to team ownership requires administrator authority. Saving affects new sessions by default; attach or refresh a selection explicitly for an existing session. Removal preserves already selected revisions. See personal library ownership and revisions.

Skill Workshop

apus skills workshop inspects and manages the learned (Workshop) skills of the selected agent. Agents create and update these skills themselves; every change applies immediately and saves the previous version first. See Skill Workshop.

apus skills workshop list
apus skills workshop changes --limit 20
apus skills workshop show release-notes
apus skills workshop show release-notes --file references/checklist.md
apus skills workshop show release-notes --version <version-id>
apus skills workshop archive release-notes --reason "Superseded by deploy-notes"
apus skills workshop restore release-notes
apus skills workshop restore release-notes --version <version-id>

Every Workshop command accepts --agent <id> and --json. archive and restore act as user in the change feed.

Related

• CLI reference
• Skills