CLI 1.4.1

Stop managing skills in a flat folder

Organize skills. Keep tools compatible.

Organized source

Organize skill changes

Tool-facing target

macOS Linux

Install via

npm i -g skill-organizer

Then run skill-organizer --version

Installs the CLI through npm and fetches the matching prebuilt binary for your platform.

Use a real source tree. Keep the tool-facing view your agent stack expects.

`skill-organizer` replaces the messy first-level skills folder with a workflow that actually scales. Organize skills by source, topic, company, or project in `skills-organized/`, then keep the generated tool-readable view synced automatically across one or many setups.

Managed skill updates

Import skills with upstream version metadata, then run skill-organizer check-updates to review new releases before you apply them.

See skill commands

Get started Star on GitHub 1 See onboarding

Main features

Built for growing skill libraries.

Keep the source tree clean for humans and the generated target predictable for tools, without resorting to manual copying, renaming, or cleanup.

Organized source, compatible output

Use a real folder hierarchy for humans while exposing the generated compatibility layer agent tools already know how to read.

Learn more

Multiple skill projects

Manage global skills and per-project targets from the same CLI instead of treating every setup as a one-off.

Disable without deleting

Hide a skill from the generated output without deleting the source folder, metadata, or the curation work behind it.

Background sync

Run watch mode in the foreground or install the service so the generated view stays fresh while you work elsewhere.

Learn more

Overlap analysis

Use an installed agent to flag duplicate or ambiguous skills before your library turns into guesswork.

Learn more

Adopt unmanaged entries

Move loose target folders into a real source tree instead of renaming, copying, or cleaning up generated output by hand.

Import and track updates

Bring in skills from skills.sh, store their source metadata, recover missing metadata when needed, inspect diffs, and update them later without losing your managed structure.

Learn more

Security check

Score every managed skill with an installed agent to surface dangerous instructions and stale reviews before they reach your tools.

Learn more

Smart features

Let an installed agent review your library.

Use the same agent CLI you already trust to surface risky instructions and overlapping skills — no separate model or service required.

Security check

Score every skill for risk before it runs.

`skill-organizer skill check-security` uses an installed agent to score each managed skill from 0 to 100, color-codes the result in the `status` tree, and offers to disable anything that crosses the danger threshold.

Ask an installed agent CLI to score each managed skill for security risk. Cached results are reused when the skill contents have not changed.

Scored by an agent you control

`skill-organizer skill check-security` reuses the same tool-selection flow as `check-overlap`: pick a Claude, Codex, OpenCode, Cursor, or Antigravity CLI, plus a model, and the same agent answers every question.

Cached when skills are unchanged

Each skill gets a content hash. Unchanged skills are skipped on the next run; `--force` re-analyzes everything when you want a fresh opinion.

Visible in the status tree

The risk score and reason land in the skill metadata, and the `status` tree shows a Safe | Warning | Danger chip per skill so the risk surface is obvious at a glance.

Overlap check

Find overlapping skills before routing gets messy.

`skill-organizer skill check-overlap` uses an installed agent to review your managed skills for duplicate or partial overlap, then groups the findings with explanations and cleanup guidance.

skill-organizer skill check-overlap

# Potential Overlap Groups

Group 1

Skills:

personal/coding/frontend-project-bootstrap
personal/react/react-project-bootstrap

Overlap:

■ Duplicate (92/100)

Why the overlap:

Both bootstrap modern TypeScript projects with the same tooling stack and validation workflow. The React version is effectively a specialization of the frontend version, but the descriptions are close enough that routing could be ambiguous.

Recommendation:

Merge them or make the separation explicit: reserve the frontend skill for framework-agnostic SPA or library bootstraps and the React skill only for repos that require React-specific files, conventions, and examples.

Group 2

Skills:

3rdparty/mattpocock/write-a-prd
3rdparty/mattpocock/prd-to-plan
3rdparty/mattpocock/prd-to-issues
3rdparty/mattpocock/request-refactor-plan

Overlap:

■ Partial (76/100)

Why the overlap:

These all sit in the planning-artifact pipeline: turning ideas or refactors into structured docs, phased plans, or GitHub issues. They are not duplicates, but their entry points and output boundaries are close enough that a user asking to plan work could plausibly match several.

Recommendation:

Define a strict workflow boundary: write-a-prd creates requirements, prd-to-plan converts an approved PRD into an implementation plan, prd-to-issues converts a finalized PRD into tickets, and request-refactor-plan is reserved for codebase refactors.

Compatibility

Works with the tools you already use.

Keep one organized source tree and generate the flat target expected by Claude Code, OpenCode, Codex, Cursor, and Antigravity.

Works with

Why use it

A cleaner way to manage skills long term.

One organized source of truth for human editing
Tool-readable output that existing agent tools already understand
Manage multiple skill targets with one consistent workflow
Disable or re-enable skills without deleting your curation work
Non-destructive sync that leaves unrelated target entries alone
Import skills from skills.sh and keep their upstream provenance

First run

Install, onboard, and start organizing.

The demo mirrors the real CLI flow: install the binary, run onboarding, and confirm the project is managed before you start reorganizing skills.

Install the CLI, then verify the exact binary you will use before touching a project.

Install once

Install from npm, Homebrew, or a release binary, then verify the CLI before touching your skills folder.

Onboard the target

Use the guided flow to create the project config, select the target, and set up the sibling skills-organized source tree.

Operate from source

Once onboarded, edit the nested source tree and let sync, watch mode, or the background service keep the generated view current.

Keep skills updated

Keep your skills updated.

Managed adds using `skills.sh` keep source and version metadata, so `skill-organizer check-updates` can find newer upstream releases, report skipped skills that are missing that metadata, and `skill-organizer skill try-find-metadata` can help repair older imports before you update them.

Add a managed skill from skills.sh so the CLI stores its upstream source and version metadata in your source tree.

Add with provenance

Managed imports keep source and version metadata so later update checks know exactly which upstream release to compare against.

Review what changed

`skill-organizer check-updates` surfaces managed skills with newer upstream versions, reports skipped skills that are missing tracked import metadata, and supports diff inspection before you choose what to update.

Update without losing structure

Selected skills are backed up into `.old/`, refreshed in the source tree, and synchronized back into the generated tool-facing target automatically.

Service and watch mode

Stop treating sync like manual maintenance.

Use watch mode while actively editing, or install the service when you want the flat target to stay current in the background.

Foreground watch Watched registry Background service Log level control

Registry

Feed the watcher with project configs

skill-organizer watched add ~/.agents/.skill-organizer.yml
skill-organizer watched list

The watched registry is the handoff between one-off setup and continuous sync.

Background sync

Install, start, and inspect the service

skill-organizer service install
skill-organizer service start
skill-organizer service status
skill-organizer service log-level set debug

Once enabled, the source tree becomes the real editing surface while the generated view stays fresh automatically.

FAQ

Questions that come up early.

Why not edit the flat target folder directly?

Because that view is generated. Editing the source tree keeps structure, naming, and metadata consistent while sync rebuilds the tool-facing layout safely.

Which agent tools work with skill-organizer?

Use the generic .agents target for tools that read ~/.agents/skills, or onboard directly for Claude Code, Codex, and Antigravity. The overlap checker can also invoke installed agent CLIs such as Claude Code, OpenCode, Codex, Cursor, and Antigravity.

Can I hide a skill without deleting it?

Yes. skill-organizer skill disable marks the source skill as disabled and removes it from the generated view on the next sync.

Do I have to run sync manually every time?

No. You can run sync on demand, use the foreground watcher, or install the background service to keep everything fresh automatically.

What does the overlap check do?

It asks an installed coding agent to analyze your managed skills for duplication or overlap, renders grouped reports, and can open a plan-only flow or save a remediation prompt under plans/ for tools without verified interactive plan mode.

Can I import skills from skills.sh and update them later?

Yes. skill-organizer skill add imports skills from skills.sh into the managed source tree, stores source and version metadata, skill-organizer skill check-updates lets you review diffs and apply updates later with automatic backups, and skill-organizer skill try-find-metadata can help recover missing metadata for older imports.

Documentation

Pick the path you need.

Start with install if you are new, onboarding if you are wiring up a skills location, or reference if you want the exact command surface for sync, service, overlap analysis, and completion scripts.

Install guide Install from npm, Homebrew, or direct binaries and verify the CLI before your first project. Onboard a tool Follow the guided flow for generic .agents locations or tool-specific layouts like Claude Code and Codex. Command reference Jump to the exact syntax for sync, service, overlap analysis, watch mode, and completion output.