skills-manage

skills-manage is the operational skill for managing shared skills, baseline exposure, and project-level skill activation.

It turns the policy in skills-org.md into actionable workflows.

---

What this skill is for

Use skills-manage when you want to:

• install a skill into the shared implementation repository
• expose a skill as a user-level baseline skill
• link a skill into one or more projects
• delete a skill safely after checking dependencies
• move or rename a skill while updating managed symlinks
• set or clear baseline exposure without reinstalling
• review the current skill layout for overlap, baseline quality, and structural problems

---

Quick start

From the repository root, you can use the helper scripts directly.

Inspect an existing skill

scripts/inspect-skill-refs skills-manage --project ~/path/to/project

This reports the shared implementation, user-level baseline links, and project-level activation paths for the named skill.

Preview linking a skill into baseline and a project

scripts/install-skill-links skills-manage \
  --baseline-agent claude \
  --project ~/path/to/project \
  --dry-run

Use --dry-run first to inspect the planned symlink changes before applying them.

Review baseline and project usage

scripts/review-skill-usage --project ~/path/to/project

This produces a JSON report covering shared skills, baseline exposure, overlap candidates, and baseline recommendation gaps.

Typical usage flow

1. Inspect the current state for a skill.
2. Preview the intended change with --dry-run.
3. Apply the change only after the planned paths look correct.
4. Re-run inspection or review to confirm the final state.

Source-of-truth model

This skill follows the rules in skills-org.md.

Shared implementation

~/.agent/skills/<skill>

This is the only place where the real skill implementation should live.

User-level baseline exposure

~/.claude/skills/<skill>
~/.config/opencode/skills/<skill>
~/.pi/agent/skills/<skill>

These are runtime views for user-level baseline skills.

Project-level activation

<project>/.agents/skills/<skill>

This is the primary project-level entrypoint.

Claude Code compatibility entry

Preferred:

<project>/.claude/skills -> ../.agents/skills

Fallback:

<project>/.claude/skills/<skill> -> ../../.agents/skills/<skill>

---

Core principles

• shared implementation lives in one place only
• runtime views are created via symlinks
• inspect before mutate
• delete/move/rename always require dependency inspection first
• prefer project-level placement when uncertain
• audit broken symlinks after every mutation

---

Supported operations

1. Install skill

Supports:

• installing or registering a skill under ~/.agent/skills
• optionally setting it as baseline
• optionally linking it into one or more projects

Typical install decisions:

• what is the canonical skill name?
• should it be baseline?
• if baseline, which agents should receive links?
• should it also be linked into projects?

---

2. Delete skill

Supports:

• inspecting reverse dependencies first
• showing baseline/project references before delete
• deleting shared implementation only after confirmation
• cleaning broken symlinks in managed locations

---

3. Move / rename skill

Treats rename/move as migration.

Supports:

• inspecting reverse dependencies first
• showing migration plan before execution
• updating managed user/project symlinks
• auditing broken symlinks after migration

---

4. Set / clear baseline

Supports:

• adding baseline links without reinstalling the shared skill
• removing baseline links without touching project activation
• selecting which agents are affected

---

5. Skill review

Produces a read-only report covering:

• overlapping skills
• baseline removal candidates
• baseline addition candidates
• structural inconsistencies in managed directories

Uses:

• skills-baseline.md as the baseline recommendation source
• skills-org.md as the structural/layout authority

---

Helper files

Main skill entry

• SKILL.md

Policy references

• skills-org.md
• skills-baseline.md

Operational docs

• docs/operations.md
• docs/symlink-safety.md

Helper scripts

• scripts/inspect-skill-refs
• scripts/install-skill-links
• scripts/remove-skill-links
• scripts/move-skill-links
• scripts/review-skill-usage

---

Current maturity

This skill is currently implemented as:

• an operational SKILL.md
• supporting docs
• helper scripts for inspection, linking, removal, migration, and review

The current implementation already supports:

• inspection and dry-run style management workflows
• baseline/project link management
• structural review

It can be extended further with:

• richer import/install flows from arbitrary local paths or repositories
• broader automatic project discovery for dependency scans
• stronger overlap/review heuristics

---

Rule of thumb

If you are changing where a skill is exposed, use skills-manage.

If you are changing what a skill does internally, edit that skill directly instead.