# Organize Skills

Audit and reorganize a Claude Code / Codex skill library, enforce a naming convention...

- Repository: https://github.com/OpenClaudia/openclaudia-skills (724 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-29
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add OpenClaudia/openclaudia-skills --skill organize-skills -g -a claude-code -y`
Codex: `npx skills add OpenClaudia/openclaudia-skills --skill organize-skills -g -a codex -y`
Cursor: `npx skills add OpenClaudia/openclaudia-skills --skill organize-skills -g -a cursor -y`
Gemini CLI: `npx skills add OpenClaudia/openclaudia-skills --skill organize-skills -g -a gemini-cli -y`

## Description

Audit and reorganize a Claude Code / Codex skill library, enforce a naming convention (prefix each skill by which backend or product it touches), rename skills consistently, fix the symlinks and cross-references a rename breaks, and report broken symlinks and stale name references. Use when the user says "organize my skills", "rename these skills", "clean up the skill library", "enforce a skill naming convention", or "fix broken skill symlinks".

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Organize Skills

Reorganize a skill library so names encode what each skill actually touches, and keep symlinks and
cross-references consistent when you rename.

Many setups keep ONE canonical skill library in a shared dir and symlink it into each tool's hub
(e.g. `~/.claude/skills/`, `~/.codex/skills/`). Some skills live inside a project repo and are
symlinked into the hub. A single rename can therefore touch several symlinks plus every doc that
references the old name, that fan-out is what this skill manages.

## Step 1, Inventory

List every skill and where it really lives. A hub entry is usually a symlink to the canonical dir:

```bash
for hub in <hub-1> <hub-2>; do
  echo "== $hub =="; ls -la "$hub"
done
```

Resolve each name to its real directory with `readlink -f`. Note which skills live in a project repo
versus the shared library, repo-resident renames must be `git mv` in that repo.

## Step 2, Classify by backend (the naming rule)

The convention: **the prefix names the backend the skill depends on**, decided by what it actually
calls, not by its topic. Grep each skill dir for the tell-tale dependency:

```bash
grep -rlE "<api-host>/api|/api/<x>|<db-client>|<AUTH_TOKEN_NAME>" "$skill_dir"
```

- Calls a specific product's API / database → that product's prefix (e.g. `acme-*`).
- Pure-local (browser automation, offline SOP, file processing, no backend) → a generic/local prefix.
- Keep a topical infix when a family is large (e.g. `acme-seo-*` vs `acme-reddit-*`) so related skills sort together.

State the classification back to the user before renaming. A skill that *feels* product-specific but
makes zero backend calls belongs in the local bucket, and vice versa, go by the dependency.

## Step 3, Rename (and fix everything a rename breaks)

For each rename `OLD → NEW`:

The rest: https://github.com/OpenClaudia/openclaudia-skills/blob/HEAD/skills/organize-skills/SKILL.md