# Skill Optimizer

> An open-source Agent Skills lifecycle toolkit for mining, personalizing, and generalizing SKILL.md files for coding agents like Claude Code, Codex, Cursor, and Gemini CLI.

Skill Optimizer is an open-source toolkit hosted on GitHub under the MIT license, built by hqhq1025, that manages the full lifecycle of Agent Skills — the `SKILL.md`-based instruction files used by coding agents. The current release is **v2.0.0**, a major redesign from the original single-skill optimizer, now split into three focused agent skills. It targets developers who work with AI coding agents and want to systematically capture, tune, and share reusable workflows.

## What It Is

Skill Optimizer provides three distinct agent skills — `skill-miner`, `skill-personalizer`, and `skill-generalizer` — each handling a different phase of the skill lifecycle. Rather than treating skill creation as a one-time task, the toolkit treats it as an ongoing process: discovering what workflows are worth capturing, adapting them to a specific user's environment, and preparing them for public distribution. The project is written primarily in Python and is compatible with agents that support the Agent Skills folder convention.

## The Three-Skill Architecture

The toolkit deliberately separates three jobs that the original single optimizer conflated:

- **skill-miner** scans coding-agent session history, memory summaries, repo notes, repeated scripts, and project folders to surface recurring intents, tool chains, and verification patterns. It includes `scripts/scan_sessions.py` for a deterministic first-pass scan of Codex, Claude Code, Gemini/Antigravity task files, and exported transcripts.
- **skill-personalizer** audits installed skills against a user's real phrasing, preferred CLIs, MCP tools, paths, aliases, and verification commands. It checks for undertrigger, overtrigger, and unnecessary-question friction, preserving the original optimizer's audit checks (trigger fit, user reaction, workflow completion, token economics, and P0/P1/P2 fixes).
- **skill-generalizer** strips private paths, credentials, account names, and internal repo facts, then packages the result with portable commands, public README claims, and frontmatter describing when to use the skill — making it ready for GitHub, marketplaces, or team sharing.

## Platform Support

The toolkit supports a broad range of coding agents:

- **Codex** — native Agent Skills, plus optional plugin metadata; install to `~/.codex/skills/`
- **Claude Code** — native skills in personal, project, and plugin scopes; install to `~/.claude/skills/`
- **Cursor** — native Agent Skills and rules/commands; discoverable by Agent
- **OpenCode** — native `skill` tool with repo/home skill discovery
- **Gemini CLI / Google agents** — Agent Skills open format documented by Google; `GEMINI.md` remains the always-on context mechanism

The recommended public layout is `skills/<name>/SKILL.md` in the repo, with install instructions copying into `.agents/skills/` or the target agent's native skill directory.

## Setup Path

Installation can be triggered directly from an agent chat by pasting a single command referencing the GitHub URL, or performed manually via `git clone` and `cp` commands. The README provides explicit paths for Codex-only, Claude Code-only, and generic agent installs. The `scan_sessions.py` script accepts flags for date range (`--days`), result limit (`--limit`), minimum recurrence count (`--min-count`), external export files (`--export`), and custom pattern files (`--patterns`).

## Update: v2.0.0 — Skill Lifecycle Toolkit

The v2.0.0 release, published on 2026-05-14, is described in the repository as a major redesign. The original project was a single skill optimizer; v2.0.0 splits the work into three purpose-built skills with distinct optimization directions. The repository was last updated on 2026-05-15 and has accumulated 77 stars and 3 forks since its creation. The project also publishes an `llms.txt`, `llms-full.txt`, and `repo-metadata.json` for AI and search visibility.

## Features
- Mine coding-agent session history to surface skill-worthy workflows
- Audit and personalize installed skills to match user habits and tools
- Generalize personal skills for public GitHub or marketplace distribution
- scan_sessions.py script for deterministic first-pass session scanning
- Support for Codex, Claude Code, Cursor, OpenCode, and Gemini CLI
- Trigger fit, overtrigger, and undertrigger auditing
- Token economics and P0/P1/P2 fix prioritization
- Frontmatter generation for public skill packaging
- Private context stripping for publishable skills
- llms.txt and structured metadata for AI visibility

## Integrations
Claude Code, Codex, Cursor, OpenCode, Gemini CLI, GitHub, MCP tools

## Platforms
LINUX, API, CLI

## Pricing
Open Source

## Version
v2.0.0

## Links
- Website: https://hqhq1025.github.io/skill-optimizer/
- Documentation: https://github.com/hqhq1025/skill-optimizer
- Repository: https://github.com/hqhq1025/skill-optimizer
- EveryDev.ai: https://www.everydev.ai/tools/skill-optimizer