/skills-management

name: skills-management
description: Search, find, discover, install, remove, update, review, deduplicate, list, move, optimise, and iterate on skills for AI coding agents. Use when user asks "find a skill for X", "install skill", "remove skill", "update skills", "list skills", "deduplicate skills", "why are two skills shown", "choose the canonical skill", "check for skill conflicts", "review skill quality", "move skill", "check for updates", "optimise skill", "audit skill edits", "trigger test skill", or "transfer skill across agents". Includes duplicate-free installation preflight and SkillOpt-style training loops. Do not use for creating skills from scratch (use /skill-creator instead).

Skills Manager

Quick Reference

| Task | Command | |------|---------| | List all | `python3 scripts/list_skills.py` | | List by scope | `python3 scripts/list_skills.py -s user` or `-s project` | | Show details | `python3 scripts/show_skill.py <name>` | | Review skill | `python3 scripts/review_skill.py <name>` | | Delete | `python3 scripts/delete_skill.py <name>` | | Delete from agents | `python3 scripts/delete_skill.py <name> --all-agents --force` | | Move to user | `python3 scripts/move_skill.py <name> user` | | Move to project | `python3 scripts/move_skill.py <name> project` | | Audit duplicate names | `python3 scripts/audit_skill_duplicates.py` | | Preflight install | `python3 scripts/audit_skill_duplicates.py --candidate /path/to/skill --fail-on-conflict` | | Create new | Use `/skill-creator` | | **Optimize & Iterate (SkillOpt-style)** | | | Plan optimisation | `python3 scripts/optimize_skill.py <name> --tasks tasks.jsonl --dry-run` | | Run optimisation | `python3 scripts/optimize_skill.py <name> --tasks tasks.jsonl --output-dir runs/r1` | | Log a manual edit | `python3 scripts/log_skill_edit.py <name> --reason "..." --snapshot` | | List recent edits | `python3 scripts/log_skill_edit.py <name> --list --since 7d` | | Diff vs last snapshot | `python3 scripts/diff_skill_versions.py <name> --log --format stats` | | Diff between commits | `python3 scripts/diff_skill_versions.py <name> --git HEAD~3 HEAD` | | Trigger test | `python3 scripts/trigger_test.py <name> --cases cases.yaml` | | Generate trigger cases | `python3 scripts/trigger_test.py <name> --generate > cases.yaml` | | Transfer test | `python3 scripts/transfer_test.py <name> --all` | | Aggregate runs | `python3 scripts/aggregate_runs.py runs/*` | | Compare runs | `python3 scripts/aggregate_runs.py runs/r1 runs/r2 --compare` | | Assertion-graded run | `python3 scripts/optimize_skill.py <name> --tasks tasks.jsonl --verifier assertions` | | Multi-run variance | `python3 scripts/optimize_skill.py <name> --tasks tasks.jsonl --runs-per-task 3` | | Blind A/B compare | `python3 scripts/blind_comparator.py --skill-a runs/r1/initial_skill.md --skill-b runs/r1/best_skill.md --tasks tasks.jsonl --output-dir cmp/` | | HTML viewer | `python3 scripts/eval_viewer.py runs/r1` | | Compare two runs (HTML) | `python3 scripts/eval_viewer.py runs/r1 runs/r2 --compare` | | **Discovery & Install** | | | Find skills | `npx skills find [query]` | | Review remote skills | Fetch skills.sh pages, assess using [assessment framework](references/remote-skill-assessment.md) | | List ecosystem skills | `npx skills list` or `npx skills ls` | | Install from GitHub | `npx skills add <owner/repo@skill> -g -y` | | Remove ecosystem skill | `npx skills remove <name> -g -y` or `npx skills rm` | | Inspect installed versions | Read lock metadata and upstream state; do not assume `npx skills check` is read-only | | Update all | `npx skills update` | | Browse online | [skills.sh](https://skills.sh) | | **Multi-Agent** | | | Detect agents | `python3 scripts/detect_agents.py` | | List agent skills | `python3 scripts/list_agent_skills.py --agent cursor` | | Install to agent | `python3 scripts/install_skill.py /path --agent cursor` | | Copy between agents | `python3 scripts/copy_skill.py <name> --from claude-code --to cursor` | | Move between agents | `python3 scripts/move_skill_agent.py <name> --from claude-code --to cursor` |

Scopes and duplicate invariant

Skill discovery is consumer-specific. Codex uses `$HOME/.agents/skills` for user skills, scans `.agents/skills` from CWD to repo root, and follows symlinks. Other agents use the paths in `scripts/agents.py`; plugins add a separately managed namespaced layer.

Maintain one active implementation of a frontmatter `name` per consumer topology. Aliases to one real directory are not independent copies; identical agent-specific replicas may be necessary, but divergent global/repo/plugin copies require a canonical-source decision. Read [skill-deduplication.md](references/skill-deduplication.md) before installing, deduplicating, migrating, or resolving plugin-vs-standalone conflicts.

Operations

List Skills

python3 scripts/list_skills.py              # All skills
python3 scripts/list_skills.py -s user      # User scope only
python3 scripts/list_skills.py -f json      # JSON output

Show Skill Details

python3 scripts/show_skill.py <name>           # Basic info
python3 scripts/show_skill.py <name> --files   # Include file listing
python3 scripts/show_skill.py <name> -f json   # JSON output

Review Skill

Audits a skill against best practices and suggests improvements:

python3 scripts/review_skill.py <name>         # Review with text output
python3 scripts/review_skill.py <name> -f json # JSON output for programmatic use

**Checks performed:**

• Name format (lowercase, hyphens, max 64 chars, gerund form)
• Name matches directory name
• Description quality (triggers, negative triggers, third person, specificity)
• XML angle brackets in frontmatter (security)
• Forbidden docs files (README.md, CHANGELOG.md)
• Body length (warns if >500 lines)
• **Token footprint** (300-2000 tokens target per SkillOpt; warns at 2000, penalises at 4000)
• **Procedurality** (instance-specific markers