Skills Management

Skills Manager

Quick Reference

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 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 — filenames, literal numbers, task references — should be rare)
• Patch-friendliness (anchor density: ##/### headings + **Label:** markers needed for reliable insert_after edits)
• Slow-update section integrity (<!-- SLOW_UPDATE_START --> / <!-- SLOW_UPDATE_END --> markers must be balanced and unnested)
• Time-sensitive content
• Path format (no Windows backslashes)
• Reference depth (should be one level)
• Table of contents for long files

After reviewing: Read the skill's SKILL.md and apply the suggested fixes directly.

Delete Skill

CRITICAL: Always use AskUserQuestion to confirm before deleting: "Are you sure you want to delete the skill '[name]'? This cannot be undone."

python3 scripts/delete_skill.py <name>              # Claude Code only, with confirmation
python3 scripts/delete_skill.py <name> --force      # Skip confirmation prompt
python3 scripts/delete_skill.py <name> -s project   # Target specific scope
python3 scripts/delete_skill.py <name> -a cursor    # Delete from specific agent
python3 scripts/delete_skill.py <name> --all-agents --force  # Delete from all agents

Multi-agent deletion: Skills installed via npx skills add may exist in multiple agent directories. The default mode (no flags) deletes from Claude Code only and warns if copies remain in other agents. Use --all-agents to delete from every detected agent at once.

For ecosystem-installed skills, prefer npx skills remove <name> -g -y first. Use delete_skill.py --all-agents as fallback for manual cleanup.

Move Skill

python3 scripts/move_skill.py <name> user      # Project → User (personal)
python3 scripts/move_skill.py <name> project   # User → Project (share with team)
python3 scripts/move_skill.py <name> user -f   # Overwrite if exists

Modify Skill

1. Run python3 scripts/show_skill.py <name> to locate it
2. Edit SKILL.md directly at the returned path

Create New Skill

Use the /skill-creator skill for guided creation with proper structure.

Optimize a Skill (SkillOpt-style)

Treat a skill as a trainable text artefact: bounded edits + held-out validation gate + rejected-edit buffer + epoch-wise slow update. See references/skill-optimization.md for the full method (Microsoft, arXiv 2605.23904, May 2026).

When to use this loop:

• Skill already exists and underperforms on a measurable task set
• You have (or can write) a verifier — exact-match, scored output, or LLM judge
• You can produce 20-100 representative tasks with reference answers

When NOT to use:

• Task has no measurable success signal — bounded text optimisation needs a gate
• Creating a skill from scratch — write a v0 with /skill-creator first
• Only 1-5 tasks available — the loop needs evidence batches

Run the loop

# 1. Dry-run to see the plan (splits, schedule, prompt previews)
python3 scripts/optimize_skill.py <name> \
    --tasks tasks.jsonl --epochs 4 --edit-budget 4 \
    --output-dir runs/r1 --dry-run

# 2. Real run
python3 scripts/optimize_skill.py <name> \
    --tasks tasks.jsonl --output-dir runs/r1 \
    --optimizer-cmd "claude -p --model claude-opus-4-7" \
    --target-cmd  "claude -p --model claude-haiku-4-5-20251001"

# 3. Inspect
cat runs/r1/optimization_report.md
python3 scripts/diff_skill_versions.py <name> --files \
    runs/r1/initial_skill.md runs/r1/best_skill.md --format stats

The loop produces best_skill.md, optimization_report.md, edit_apply_report.json, rejected_buffer.json, and meta_skill.json (optimiser-side only — not shipped).

Manual-edit audit trail

For edits made outside the loop (hand-tweaks, bug-fix follow-ups), keep a lightweight log:

# After saving an edit
python3 scripts/log_skill_edit.py <name> \
    --reason "tightened insert_after target" \
    --source from-bug --ref "issue #42" --snapshot

python3 scripts/log_skill_edit.py <name> --list --since 30d
python3 scripts/diff_skill_versions.py <name> --log

--snapshot saves a copy under <skill>/.skill_snapshots/SKILL.<sha8>.md so the diff helper can show actual content, not just hashes.

Protected slow-update section

A skill that gets optimised iteratively should include a markup-fenced region for longitudinal guidance:

<!-- SLOW_UPDATE_START -->
<!-- This block is managed by the epoch-boundary slow-update process.
     Step-level edits never modify it. -->
<!-- SLOW_UPDATE_END -->

scripts/review_skill.py flags unbalanced or nested markers. scripts/optimize_skill.py refuses to apply step-level edits that target content inside this region.

Trigger and transfer tests

# Auto-generate candidate trigger cases from the skill's description
python3 scripts/trigger_test.py <name> --generate > cases.yaml
# Curate, then run
python3 scripts/trigger_test.py <name> --cases cases.yaml --threshold 0.8

# Verify skill lands and parses in other agents
python3 scripts/transfer_test.py <name> --all --scope global

Rich grading: assertions verifier

Pass --verifier assertions to grade each rollout against declarative assertions[] from tasks.jsonl. The grader returns per-assertion pass/fail with evidence, extracted claims, AND a critique of the assertions themselves (eval_feedback) — a meta layer that flags weak or non-discriminating checks. optimization_report.md aggregates these into an "Assertion critique" section.

// tasks.jsonl entry for --verifier assertions
{"id":"t1","prompt":"...","assertions":["The output is a valid JSON array","Each item has a name field"]}

Variance: multi-run per task

Pass --runs-per-task 3 to run each task N times. rollouts.jsonl records score_mean and score_stddev; validation gate uses the mean. Use this when the verifier is noisy or the agent's behaviour is non-deterministic.

Blind A/B comparison

Independent verdict on whether best_skill.md is actually better than initial_skill.md — important because the SkillOpt gate uses the same verifier that proposed the edits, which can be self-confirming.

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/r1

Per task: both skills run on the same prompt, outputs presented as X/Y to an independent judge with randomised labels. Aggregated to comparison_report.{json,md}.

HTML viewer for a run

python3 scripts/eval_viewer.py runs/r1                    # opens in browser
python3 scripts/eval_viewer.py runs/r1 runs/r2 --compare  # side-by-side

Single-page static HTML: per-epoch chart, accepted/rejected edit timelines, slow-update history, per-task rollouts with grading, initial→best diff. No JS / CSS deps.

Discover & Install Skills

Search and install skills from the open agent skills ecosystem via the Skills CLI (npx skills). Browse at skills.sh.

Find Skills

npx skills find [query]              # Interactive search
npx skills find react performance    # Keyword search
npx skills find pr review            # Search by task

Install from Ecosystem

Mandatory preflight: determine the candidate frontmatter name and run the duplicate auditor before installation. If the name exists, update/reuse the canonical copy instead. For intentional cross-agent replicas, document the need and use install_skill.py --allow-duplicate-name only after review.

For a locally maintained canonical source, prefer install_skill.py --link: every agent sees the same real directory and future edits cannot make copied installs drift. Use a copy only when the consumer cannot follow symlinks or deliberately needs an isolated snapshot.

npx skills add <owner/repo@skill> -g -y    # Install globally, skip prompts
npx skills add vercel-labs/agent-skills@vercel-react-best-practices -g -y

List Ecosystem Skills

npx skills list                      # List all installed ecosystem skills
npx skills ls                        # Alias
npx skills list -g                   # Global skills only
npx skills list -a cursor            # Skills for a specific agent

Remove Ecosystem Skills

Uninstalls skills installed via npx skills add. For locally-created skills, use python3 scripts/delete_skill.py instead.

CRITICAL: Always confirm with the user before removing.

npx skills remove <name> -g -y       # Remove a global skill, skip prompt
npx skills rm <name>                 # Alias, with confirmation prompt
npx skills remove <name> -a cursor   # Remove from specific agent
npx skills remove --all -g -y        # Remove all global ecosystem skills

Check & Update

npx skills check                     # Check for available updates
npx skills update                    # Update all installed skills

Treat npx skills check as potentially mutating: some CLI versions update during check, and check --help may enter the same workflow. Do not run it for read-only inspection unless the user already authorized updates. Prefer repository HEAD, manager lock metadata, and installed hashes for a read-only freshness comparison. After any managed update, rerun the duplicate audit because stale lock entries can recreate removed copies.

When to Search

Use npx skills find when the user:

• Asks "how do I do X" where X is a common task
• Says "find a skill for X" or "is there a skill for X"
• Wants specialized capabilities (design, testing, deployment, etc.)