Skillager

Skillager is a local skill library and approval layer. It discovers skills, records the exact content you review, and helps your agent use the smallest relevant set for each project.

• Create and maintain personal skills in one versioned library.
• Use project, package, and shared skills without moving them.
• Keep reviewed skills on demand until your agent needs them.

discover or create → review exact content → let the agent find what helps

Quickstart

Install Skillager once, then set it up in a project:

uv tool install skillager
# or: pipx install skillager

cd my-project
skillager setup --agent codex

Use --agent claude for Claude.

Setup finds skills for the current project and asks which ones you trust. It then installs a small project skill that teaches your agent how to use Skillager. It does not modify AGENTS.md or CLAUDE.md.

Restart your agent in the project, then describe your goal:

Check Skillager, then help me build a Python GIS service. Use reviewed skills where they help, and keep one-off skills on demand.

Your agent checks readiness, searches reviewed skills when useful, and avoids adding one-off skills to every session. If Skillager needs your help, the agent gives you the exact command to run.

You Decide; Your Agent Operates

Reviewing a skill does not add it to every chat. Tell your agent whether the work is one-off or recurring; it will keep the skill on demand or make a small recurring set easy to reach.

Work With Your Agent

Use prompts like these:

• Find help for a task: “Find the best available skills for <goal>. Show me the shortlist before changing the project.”
• Prepare recurring work: “We will do <workflow> repeatedly in this project. Create the smallest useful Skillager setup and leave everything else on demand.”
• Create a skill you own: “Create a personal skill for <purpose>. Show me the draft, then ask before approving it for use.”
• Adopt an external skill: “Find the external skill called <name> and prepare to add it to my personal library. Show me what you found and ask before importing it.”
• Recover an older version: “Show me the saved versions of my <name> skill, explain what changed, and ask before restoring anything.”

Your Personal Library

When you approve a skill, complete setup with existing approvals, create your first personal skill, or confirm your first import, Skillager creates ~/.skillager/library and starts Git history. You do not need to initialize it first.

Run library init before your first skill only to choose a different location or skip Git history:

skillager library init --path ~/skills/personal
skillager library init --no-git

Run skillager library status to see the library location and health.

Git keeps library content history; SQLite keeps approvals and their decision history. Search reuses a persistent SQLite index. Back up the library and approval state together; see storage and recovery.

Search accepted owned skills with skillager search "database migration" --scope library --json. The default scope includes available workspace sources. Both return metadata only; see search scope and freshness.

After you or your agent edits a personal skill, Skillager asks you to review the change before the skill can run.

Preview a project Add, Update, or mode change with skillager expose <skill-id> --mode native --agent codex --scope project --dry-run --json. The preview lists all projected file changes and returns a confirmation command bound to that source and target. See the agent CLI guide for confirmation and refusal handling.

Local native adoption, named router grouping/membership/ungrouping, and preserved native removal use complete expose --request-json plans. Exact-copy Full/Stub changes use optional --exposure-id. See local exposure plans for the closed request schema, preservation rules, complete effects and recovery.

Removal previews use skillager expose --remove <exposure-id> --agent codex --json and disclose the complete removed tree and target-folder permissions before confirmation.

Importing copies one external skill into your library and leaves the original where it is.

Edit personal skills at the library path Skillager shows you. If you edit a project copy instead, Skillager stops before replacing it; it does not merge that edit back into your library.

Add Existing Skill Repositories

Setup discovers skills in the current project and installed environments. Register a separate skill repository when you want its reviewed skills available across projects:

skillager collection add ~/skills/workflows --name workflows
skillager setup --collection workflows --agent codex

Registering a repository only adds discovery. Approving its skills preserves verified copies in your library while leaving the repository intact. The same policy covers project, environment, package, and native skills, including project-only approvals. Canonical copies are reusable across projects; exposure remains a separate action.

Backfill skills approved before this policy with skillager library sync --approved. Use skillager library sync --status --json to inspect current lineage and conflicts without copying or approving anything. Customized, blocked, or pinned library copies are protected; a partial result lists what still needs attention.

Before Skillager Changes Anything

Skillager asks you before it:

• lets a new or changed skill run;
• imports or restores a personal skill;
• discards an edit made to a project copy;
• approves content that its checks flag as risky; or
• uses a skill that explicitly excludes your agent.

Skillager never silently moves an external skill, replaces a locally edited copy, or pulls from and pushes to Git remotes.

Codex and Claude can also load skills installed directly in their own folders. Skillager cannot review or block those skills.

Run this when something looks wrong:

skillager doctor --agent codex

Learn More

• Use Skillager
• Understand how agents operate Skillager
• Publish skills in packages and repositories
• Review the trust and safety model
• See command and behavior changes

Development

Run the full local check:

uv run --python 3.13 python scripts/check.py

The opt-in synthetic search benchmark generates 5,000 approved skills locally and measures the real CLI without downloads or private data.

External contributions are not being accepted yet while the API and workflow settle.

Skillager is released under the MIT License.