---
slug: "manage-agent-skills"
source_type: "clawhub"
source_url: "https://clawhub.ai/skills/manage-agent-skills"
repo: ""
source_file: "description"
---
---
name: manage-agent-skills
description: Audit, search, enable, disable, and apply presets to installed Agent Skills without deleting their files. Use when the user wants to reduce idle skill context, keep rarely used skills manual, inspect newly installed skills on demand, or manage skills across Codex, Claude Code, GitHub Copilot CLI, OpenClaw, and Hermes Agent.
---

# Manage Agent Skills

Use the bundled `scripts/skillctl.py` for deterministic, on-demand management.
Never start a daemon or watcher. Discover current skills again on every invocation.

## Workflow

1. Run `doctor` or `status` before changing anything.
2. Use `search` to resolve exact skill names.
3. Preview mutations with `--dry-run`.
4. Apply the requested mutation.
5. Report the platform, affected skills, config or native command used, backup path,
   and whether a new agent session is required.

Choose the Python launcher available on the current operating system (`python`
on Windows, commonly `python3` on macOS/Linux) and resolve the skill directory
before running the script.

Windows PowerShell:

```powershell
$skillctl = "<skill-directory>\scripts\skillctl.py"
python "$skillctl" doctor
python "$skillctl" --platform codex status
python "$skillctl" --platform all search azure
```

macOS/Linux:

```bash
skillctl="<skill-directory>/scripts/skillctl.py"
python3 "$skillctl" doctor
python3 "$skillctl" --platform codex status
python3 "$skillctl" --platform all search azure
```

Mutation commands use the same arguments on every operating system:

```text
<python> <skillctl> --platform claude disable deploy --dry-run
<python> <skillctl> --platform claude disable deploy
<python> <skillctl> --platform copilot enable my-skill --dry-run
<python> <skillctl> --platform openclaw disable browser-tools --dry-run
<python> <skillctl> --platform hermes --hermes-scope telegram disable shell-tools --dry-run
```

For automation, pass `--json` either before or after the command. Use the
format that keeps the caller's command template readable:

```text
<python> <skillctl> --platform all --json status
<python> <skillctl> --platform all status --json
```

Mutations require an explicit `--platform codex`, `--platform claude`, or
`--platform copilot`, `--platform openclaw`, or `--platform hermes`. Selectors
are exact names, `group:<name>`, `path:<path>`, or `all`; partial names are
intentionally rejected. Hermes defaults to global scope; pass
`--hermes-scope <platform>` for a platform-specific disable.

For `path:` selectors, use the native absolute path printed by `search`, and
quote the entire selector when it contains spaces:

```text
Windows: path:C:\skills\demo\SKILL.md
macOS:   path:/Users/alice/.agents/skills/demo/SKILL.md
Linux:   path:/home/alice/.agents/skills/demo/SKILL.md
```

Do not translate paths between operating systems; matching uses the path rules
of the system running `skillctl.py`.

## Presets

Use a JSON preset file matching `references/presets.md`:

```text
<python> <skillctl> --platform codex preset lean --file skill-presets.json --dry-run
<python> <skillctl> --platform codex preset lean --file skill-presets.json
```

## Safety

- Do not delete, relocate, or rewrite any installed `SKILL.md`.
- Keep changes scoped to native platform controls.
- Codex edits only its marked TOML block.
- Claude Code edits only `skillOverrides` in its settings JSON.
- Copilot writes the documented `disabledSkills` setting and uses
  `copilot skill list --json` for native discovery when available.
- OpenClaw delegates mutations to `openclaw config set` so its JSON5 config is
  not normalized or hand-edited. Agent allowlists may still restrict a skill.
- Hermes writes only `skills.disabled` or
  `skills.platform_disabled.<scope>` in `config.yaml`. PyYAML may normalize
  formatting and comments, so the backup is the lossless recovery copy.
- Create a sibling `.manage-agent-skills.bak` before changing a config file.
- Protect `manage-agent-skills`, `skill-creator`, and `plugin-creator` from
  disable-all unless the user explicitly requests `--force`.
- Explain that Codex, Claude Code, OpenClaw, and Hermes changes may require a
  new session or gateway restart; Copilot follows its native command behavior.

Read `references/platforms.md` when platform semantics or support boundaries
matter. Read `references/presets.md` only when creating or applying presets.