01
Organized source, compatible output
Use a real folder hierarchy for humans while exposing the generated compatibility layer agent tools already know how to read.
Version 0.0.5 Stop managing skills in a flat folder
Organize skills. Keep tools compatible.
Organized source
Organize skill changes
Tool-facing target
macOS Linux
npm i -g skill-organizer pnpm add -g skill-organizer brew install sergiocarracedo/tap/skill-organizer 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.
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.
02
Multiple skill projects
Manage global skills and per-project targets from the same CLI instead of treating every setup as a one-off.
03
Disable without deleting
Hide a skill from the generated output without deleting the source folder, metadata, or the curation work behind it.
04
Background sync
Run watch mode in the foreground or install the service so the generated view stays fresh while you work elsewhere.
05
Overlap analysis
Use an installed agent to flag duplicate or ambiguous skills before your library turns into guesswork.
06
Adopt unmanaged entries
Move loose target folders into a real source tree instead of renaming, copying, or cleaning up generated output by hand.
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
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.
01
Install once
Install from npm, Homebrew, or a release binary, then verify the CLI before touching your skills folder.
02
Onboard the target
Use the guided flow to create the project config, select the target, and set up the sibling skills-organized source tree.
03
Operate from source
Once onboarded, edit the nested source tree and let sync, watch mode, or the background service keep the generated view current.
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 listThe 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 debugOnce enabled, the source tree becomes the real editing surface while the generated view stays fresh automatically.
Skill 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.
# 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.
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.
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.