AgentKit
DocsKitsCLI ReferenceDesktop App
BetaYou are reading docs for the beta channel (3.1.0-beta.10). Features may change before the next stable release.Switch to stable →

ak skills

ak skills remove

Remove one installed skill and its runtime record directly while preserving the shared package cache.

Use ak skills remove to delete one installed skill copy from the user Claude plugin root.

Usage

ak skills remove <kit>/<skill>

Local <kit>/<skill> removal has no command-specific flags; --dry-run, --runtime, and --scope apply only to SkillX references. Canonical references are recommended; ak:, ake:, and akm: reference shorthands are accepted.

Deletion order and limits

If the destination directory exists, the command:

  1. Removes the per-skill runtime record unless AGENTKIT_SKILL_RUNTIME=0.
  2. Removes ~/.claude/plugins/<kit>/skills/<skill>/.

The shared ~/.agentkit/cache/<runtime-hash>/ entry is preserved. If content is already absent, the command returns success without trying to clean an orphan runtime record.

Local removal is immediate. There is no prompt, dry-run, ownership/drift check, backup, snapshot, or rollback. If content deletion fails after runtime-record deletion, the content can remain without its record.

To recover, reinstall from the unchanged local kits source. Any preserved shared runtime cache may be reused, but it does not restore the deleted content.

SkillX references

With SkillX on (after ak update --ssot, or AGENTKIT_SKILLX=1), an @publisher/slug argument drops only your reference to that SkillX package. Files another owner still holds stay, a file you changed is preserved and reported, and the skill directory is removed only when it is empty. The change runs in one journaled transaction under the kit lifecycle lock. --dry-run previews it, --runtime limits it to claude-code or codex (default: every runtime with a recorded projection), and --scope selects project (default) or global.

ak skills remove @publisher/review-guardrails --scope global

Output

JSON uses kind=assets.remove with:

data.ref, data.kit, data.asset,
data.removed, data.not_installed

Removing an absent destination returns removed=false, not_installed=true, and exit 0. Human output similarly says “nothing to remove.”

Exit behavior

ExitMeaning
0Content was removed or was already absent.
1Runtime-record or content deletion failed. Missing or extra positional arguments also currently use this path. For SkillX, also offline without a verified copy, a refused credential, a path that is too long, or required recovery.
2The reference or flags were invalid. For SkillX, also SkillX or the skill store is disabled, or the alias is reserved.
4SkillX only: another AgentKit operation holds the kit lifecycle lock.
5SkillX only: the release was not found or is not entitled.
6SkillX only: an alias collision, an unowned or modified path, untrusted project state, or the lock changed during the run.
7SkillX only: the release is revoked, yanked, quarantined, or untrusted, a target path contains a link, or a digest did not match.

For malformed references, the current JSON error envelope can report exit_code: 1 while the process exits 2.