skills-manager

Stop rebuilding your tool setup for every project. Catalog skills and MCP servers once, group them by workflow, and switch each project to the capabilities it actually needs.

skills-manager is a category-based function manager for AI coding CLIs. This repository contains two independent implementations:

• OpenAI Codex CLI version →
• Claude Code CLI version →

Both versions support natural-language management, project-oriented categories, MCP migration, safety previews, and reproducible switching. They use different runtime layouts and configuration formats, so choose the implementation that matches your agent.

Why this project exists

Once you install several skills and MCP servers, three problems appear:

1. every project sees more tools than it needs;
2. related skills and MCPs must be enabled separately;
3. manual edits make it difficult to tell which project entries are safe to remove.

skills-manager turns those scattered tools into a managed function catalog:

User-level function catalog
        ↓
Categories: research / coding / office / ...
        ↓
Project receives only the selected skills and MCP servers

You can ask the agent naturally:

Scan my newly installed skills and MCP servers.
Create a research category with paper writing and reference tools.
What is the smallest useful function set for this project?
Switch the current project to research.
Switch the current project to None.

The implementation translates the request into deterministic operations, previews mutations, asks for confirmation, applies them, and validates the result.

Choose your version

The two implementations are maintained independently. Their source code and personal configuration files are not synchronized. Both guides target their respective CLI; desktop, web, and IDE integrations are not guaranteed to share the same discovery, configuration, or project-switching behavior.

Quick installation

The two Git installations use sparse checkout, so each CLI downloads only its own implementation.

OpenAI Codex CLI

PowerShell:

git clone --depth 1 --filter=blob:none --sparse https://github.com/Xue-Sir/skills-manager.git skills-manager-codex-source
git -C skills-manager-codex-source sparse-checkout set skills-manager-codex
New-Item -ItemType Directory -Force "$HOME\.codex\skills" | Out-Null
Copy-Item -Recurse ".\skills-manager-codex-source\skills-manager-codex" "$HOME\.codex\skills\skills-manager"
python -m pip install -r "$HOME\.codex\skills\skills-manager\requirements.txt"

Bash:

git clone --depth 1 --filter=blob:none --sparse https://github.com/Xue-Sir/skills-manager.git skills-manager-codex-source
git -C skills-manager-codex-source sparse-checkout set skills-manager-codex
mkdir -p ~/.codex/skills
cp -R skills-manager-codex-source/skills-manager-codex ~/.codex/skills/skills-manager
python -m pip install -r ~/.codex/skills/skills-manager/requirements.txt

Then start with:

$skills-manager Initialize the private data root, then scan my user-level skills and MCP servers.

Read the Codex guide for ownership rules, project switching, backups, and configuration.

The Codex package is stateless and portable: copying skills-manager-codex installs only the manager. It contains no runtime config, code_*, retired, or backups directories. Setup creates those under ~/.codex/skills-manager-data, and every later catalog mutation stays there.

Claude Code CLI

PowerShell:

git clone --depth 1 --filter=blob:none --sparse https://github.com/Xue-Sir/skills-manager.git skills-manager-claude-code-source
git -C skills-manager-claude-code-source sparse-checkout set skills-manager-claude-code
New-Item -ItemType Directory -Force "$HOME\.claude\skills" | Out-Null
Copy-Item -Recurse ".\skills-manager-claude-code-source\skills-manager-claude-code" "$HOME\.claude\skills\skills-manager"

Bash:

git clone --depth 1 --filter=blob:none --sparse https://github.com/Xue-Sir/skills-manager.git skills-manager-claude-code-source
git -C skills-manager-claude-code-source sparse-checkout set skills-manager-claude-code
mkdir -p ~/.claude/skills
cp -R skills-manager-claude-code-source/skills-manager-claude-code ~/.claude/skills/skills-manager

Then start with:

/skills-manager scan

Read the Claude Code guide for categories, migration behavior, commands, and configuration.

Core ideas

• Categories are project modes. Define a useful function set once and reuse it.
• Natural language is the primary interface. Commands remain available as a deterministic execution layer.
• Related capabilities can move together. Group dependent skills and MCPs instead of toggling them separately.
• Project-owned entries are preserved. A manager should remove only what it can prove it created.
• Migrations are reviewed. Newly discovered external functions are presented before adoption.
• Backups precede user configuration changes. Destructive cleanup always requires explicit confirmation.

Repository layout

skills-manager/
├── README.md
├── LICENSE
├── skills-manager-codex/
│   └── README.md
└── skills-manager-claude-code/
    └── README.md

The Codex package publishes no runtime configuration files; initialization defaults are embedded in its program. Neither implementation should publish the author's personal skills, MCP definitions, tokens, or user-level configuration.

License

Released under the MIT License.