name: skills-organization description: Organize and synchronize local agent skill directories across Codex, Claude, Cursor, and other agent tools. Use when the user asks to audit, mirror, link, migrate, or reconcile skill folders such as ~/.agents/skills, ~/.codex/skills, ~/.claude/skills, ~/.cursor/skills, or tool-specific skill directories.

Skills Organization

Use this skill when keeping local agent skill folders aligned across tools.

Core Stance

• Treat ~/.agents/skills as the canonical source of truth for personal/shared skills.
• Mirror each agent tool's normal skills path to the canonical root with a directory symlink.
• Prefer a hub-and-spoke layout over cross-linking every directory to every other directory.
• Do not blindly import product-managed, vendor-managed, plugin-cache, backup, or bundled skill directories.
• Preserve anything you replace. Move real directories to timestamped backups before creating symlinks.

On Andy's machine, verified 2026-06-10:

• ~/.codex/skills -> ~/.agents/skills
• ~/.claude/skills -> ~/.agents/skills
• ~/.cursor/skills -> ~/.agents/skills
• ~/.cursor/skills-cursor is a separate Cursor-managed skill directory; do not merge it automatically.
• ~/.codex/vendor_imports/skills is a vendor import checkout; do not merge it automatically.
• ~/.agent/skills was not present; if it exists elsewhere, audit it before using it.

Why Not Cross-Link Everything?

If ~/.codex/skills, ~/.claude/skills, and ~/.cursor/skills are symlinks to ~/.agents/skills, then adding a skill through any of those paths already lands in the shared directory. A mesh of symlinks between tool directories is harder to reason about, easier to loop, and offers no practical benefit over one canonical target.

Use this model instead:

~/.agents/skills
  ^-- ~/.codex/skills
  ^-- ~/.claude/skills
  ^-- ~/.cursor/skills
  ^-- any other personal agent skills path

Audit Workflow

1. Inventory the expected paths:

for d in "$HOME/.agents/skills" "$HOME/.codex/skills" "$HOME/.claude/skills" "$HOME/.cursor/skills"; do
  ls -ld "$d" 2>/dev/null || true
  readlink "$d" 2>/dev/null || true
done

2. Confirm the canonical root exists and contains the expected personal skills:

3. Check for non-canonical directories that might contain personal skills:

4. Classify each path:

• Symlink to ~/.agents/skills: already aligned.
• Missing path: create a symlink if the tool expects that path.
• Real directory with personal skills: reconcile into ~/.agents/skills, back up the directory, then replace it with a symlink.
• Symlink elsewhere: inspect before changing.
• Vendor/product/cache directory: leave alone unless the user explicitly asks to import from it.

Reconcile Workflow

When a consumer path is a real directory instead of a symlink:

1. List its skills with find <path> -maxdepth 2 -name SKILL.md -print.
2. For each skill folder, compare against ~/.agents/skills/<skill-name>.
3. If the skill is missing from the canonical root, copy the whole skill folder into ~/.agents/skills.
4. If the skill exists in both places, run diff -ru and show conflicts to the user. Do not choose silently.
5. Move the original directory to skills.pre-mirror-backup-YYYYMMDD-HHMMSS.
6. Create the symlink to ~/.agents/skills.

Example:

backup="$HOME/.codex/skills.pre-mirror-backup-$(date +%Y%m%d-%H%M%S)"
mv "$HOME/.codex/skills" "$backup"
ln -s "$HOME/.agents/skills" "$HOME/.codex/skills"

Only run write commands after confirming the target and backup paths are correct.

Collision Policy

• The canonical root wins by default, but never overwrite a conflicting skill without user approval.
• Identical duplicates can be treated as already reconciled.
• If two folders share a name but have different content, preserve both by copying the non-canonical copy to a temporary comparison or backup location and ask the user which version should become canonical.
• Do not delete backups as part of the sync task unless explicitly requested.

Verification

After making changes:

readlink "$HOME/.codex/skills" "$HOME/.claude/skills" "$HOME/.cursor/skills"
find "$HOME/.agents/skills" -maxdepth 2 -name SKILL.md -print | sort

The expected result is that every personal agent skills path resolves to ~/.agents/skills, and the canonical root contains the skills the user expects.

For a stronger check, create a temporary test folder only if the user agrees, then verify it appears through every symlinked path and remove the temporary folder afterward.

Safety Rules

• Do not use rm -rf for reconciliation. Move to backups instead.
• Do not merge skills.pre-mirror-backup-* folders back into source automatically.
• Do not sync plugin caches, bundled runtime skills, marketplace/vendor checkouts, or Cursor's skills-cursor directory unless the user specifically asks.
• Keep commands readable and inspectable; this task is about preserving local workflow state, not being clever.