Skills manage

Skills Manage

Turn the policy in skills-org.md into safe operational workflows.

Use this skill when the user wants to:

• install a skill into ~/.agent/skills
• expose a skill as user-level baseline for Claude Code / Opencode / Pi
• link a skill into one or more projects
• delete a skill after dependency inspection
• move or rename a skill and update managed symlinks
• set or clear baseline links without reinstalling
• review overlap, baseline choices, and structural issues in the current skill layout

Source of truth

• Real implementations live in ~/.agent/skills/<skill>
• Project activation lives in <project>/.agents/skills/<skill>
• Claude Code project compatibility prefers <project>/.claude/skills -> ../.agents/skills
• User-level baseline links live in:
  • ~/.claude/skills/<skill>
  • ~/.config/opencode/skills/<skill>
  • ~/.pi/agent/skills/<skill>

If unsure whether a skill should be baseline or project-level, recommend project-level first.

Related references

• Architecture and layout rules: skills-org.md
• Baseline recommendations: skills-baseline.md
• Operational details: docs/operations.md
• Symlink invariants and conflict handling: docs/symlink-safety.md

Safety rules

1. Inspect before mutate.
2. Delete, move, and rename always require reverse dependency inspection first.
3. Only modify managed link slots and approved roots.
4. Never treat <project>/.claude/skills as the project source of truth when .agents/skills exists.
5. If a would-be link location is a real directory or regular file, stop and ask instead of replacing it silently.
6. After every mutation, audit broken symlinks in the managed locations you touched.
7. For project links, prefer directory-level Claude compatibility first; only fall back to per-skill .claude/skills/<skill> links when necessary.

Supported operations

1. Install skill

Use this workflow when the user wants to install or register a skill into the shared repository and optionally expose it elsewhere.

Questions to ask

• What is the source of the skill: existing shared skill, local path, or another source to copy from?
• What canonical skill name should it use?
• Should it be added to baseline?
• If baseline, which user-level agent directories should receive links: Claude Code, Opencode, Pi?
• Should it also be added to one or more projects? If yes, what project root path(s)?
• If the target already exists, should it be reused, replaced, or should the operation stop?

Execution order

1. Inspect the target shared path under ~/.agent/skills/<skill>.
2. If needed, create or import the shared implementation.
3. If baseline is requested, create selected user-level symlinks.
4. If project activation is requested, create <project>/.agents/skills/<skill> links.
5. Prefer <project>/.claude/skills -> ../.agents/skills as Claude compatibility. If unavailable/conflicting, use per-skill fallback links.
6. Validate all created paths and audit broken symlinks.

2. Delete skill

Use this workflow when the user wants to remove a shared skill implementation or unlink it from runtime directories.

Questions to ask

• Do you want to delete the shared skill implementation, or only unlink baseline/project references?
• I found these dependent links and references. Should I remove all of them?
• This skill is still used by multiple projects. Do you still want to proceed?

Execution order

1. Inspect reverse dependencies across managed user-level and project-level locations.
2. Show the dependency summary to the user.
3. Require confirmation before removing the shared implementation.
4. Remove references first.
5. Remove the shared implementation only after references are handled.
6. Audit and clean broken symlinks in managed locations.

3. Move / rename skill

Treat rename and move as a migration, not a cosmetic edit.

Questions to ask

• What is the new canonical skill name/path?
• Should all managed user/project links be updated automatically?
• Should stale internal references in SKILL.md or docs be reported after migration?

Execution order

1. Inspect reverse dependencies.
2. Show the migration plan and require confirmation.
3. Rename/move the shared implementation under ~/.agent/skills.
4. Update managed user-level and project-level links.
5. Audit broken symlinks and report stale internal references if found.

4. Set / clear baseline

Use this when the shared implementation already exists and the user only wants to add or remove user-level baseline links.

Questions to ask

• Which user-level agent directories should be linked or unlinked: Claude Code, Opencode, Pi?
• Apply to all selected agents or only some of them?

Execution order

1. Confirm the shared implementation exists.
2. Inspect current user-level baseline links.
3. Add or remove selected links.
4. Validate the resulting links and audit broken symlinks.
5. Optionally mention whether the skill aligns with skills-baseline.md.

5. Skill review

Use this as a read-only advisory workflow.

Review outputs

• overlapping skills
• baseline removal candidates
• baseline addition candidates
• structural inconsistencies (broken symlinks, unexpected real dirs in managed slots, incompatible .claude/skills setups)

Questions to ask

• Which project roots should be included in the review?
• Should the review be structural-only, or also include overlap and baseline recommendations?
• Do you want recommendations only, or also a proposed cleanup plan?

Execution order

1. Inventory shared skills and current user-level baseline links.
2. Optionally inspect selected projects.
3. Use skills-baseline.md to compare current baseline against recommended baseline.
4. Report overlap candidates, baseline additions/removals, and structural issues.

Managed helper scripts

Use these scripts where appropriate instead of re-deriving filesystem logic ad hoc:

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

Validation checklist after every mutation

• Shared implementation exists at the expected path
• Intended symlinks resolve to the approved managed target
• No touched managed path is left as a broken symlink
• Project activation remains rooted in .agents/skills
• Claude compatibility is either the preferred directory symlink or an explicit per-skill fallback