Skill Optimizer

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.