Skill Organizer

skill-organizer lets you keep SKILL.md directories organized in nested folders while exposing the flat first-level skills folder that agent tools expect.

It uses an organized source tree such as skills-organized/ as the source of truth and generates a flat target folder of symlinks such as .agents/skills/, .claude/skills/, or .codex/skills/. This makes it easy to separate your own skills, third-party skills, company skills, and experiments without manually copying folders around.

Agent-first setup and onboarding instructions are documented in AGENTS_README.md.

Release automation and distribution notes are documented in docs/releasing.md.

Table Of Contents

• Getting Started
• Why
• Organized Source To Flat Target
• How It Works
• Layout
• Commands
• Shell Completion
• Disable Skills Without Deleting Them
• Example Demo Flow
• Example Status Output

Getting Started

Install skill-organizer using one of the supported distribution channels:

Using NPM

npm i -g skill-organizer

Using homebrew

brew tap sergiocarracedo/tap
brew install skill-organizer

If you prefer a direct binary download, use the GitHub Releases page:

• https://github.com/sergiocarracedo/skill-organizer/releases

Then verify the CLI is available:

skill-organizer --version

For a first-time setup, use the interactive onboarding flow:

skill-organizer onboard
skill-organizer status

If you want agent-oriented setup guidance for .agents, Claude Code, Codex, or Antigravity, see AGENTS_README.md.

Why

Most agent tools only read skill folders at the first level of their skills directory. That works for a few skills, but it becomes messy once you want to group them by source or topic.

skill-organizer solves that by keeping two views of the same skills:

• an organized source tree that you edit directly
• a flat generated target folder that your tools can read

The target folder is generated from the source tree using flattened names and symlinks, so your real skills stay organized and the tool-facing folder stays compatible.

Organized Source To Flat Target

Example source tree:

organized-skills/
├── generic
├── starter
├── my-skills/
│   ├── coding-skills/
│   │   ├── astro-performance-auditor/
│   │   └── typescript-error-explainer/
│   ├── text-skills/
│   │   ├── newsletter-copy-editor/
│   │   └── writing-style-harmonizer/
│   └── personal-workflows/
│       └── weekly-review-assistant/
├── company-skills/
│   ├── coding-skills/
│   │   ├── internal-api-checklist/
│   │   └── release-train-coordinator/
│   ├── compliance/
│   │   └── pii-review-helper/
│   └── onboarding/
│       └── engineering-ramp-up-guide/
├── community-skills/
│   ├── frontend/
│   │   ├── design-token-curator/
│   │   └── visual-regression-triager/
│   └── content/
│       └── markdown-link-fixer/
└── experimental/
  └── research/
    └── prompt-pattern-lab/

Generated target folder: