Skill Optimizer — Agent Skill Optimization Toolkit

Compress, benchmark, and iteratively improve SKILL.md files for AI agents. Reduce skill token count by 40-70% while maintaining accuracy.

SKILL.md files define how AI agents approach specific tasks — but verbose skills waste tokens and slow down inference. Skill Optimizer parses your skill definitions, applies multiple compression strategies, benchmarks them against test cases, and iteratively refines them until you get the optimal balance of brevity and performance.

---

Features

• SKILL.md parsing — Parse structured skill files with support for headings, code blocks, examples, constraints, and metadata sections. Understands the SKILL.md format natively.
• 5 compression strategies — Apply whitespace normalization, sentence deduplication, synonym substitution, example summarization, and structural compression. Each strategy is independently toggleable.
• LLM-powered benchmarking — Evaluate compressed skills by running them against test prompts and comparing output quality to the original. Uses GPT-4o or Claude as judge models.
• Iterative optimization — Run multi-round compression cycles that automatically test, measure, and refine. Stops when quality drops below your configured threshold.
• CLI tool — Full command-line interface for init, compress, benchmark, and optimize workflows. Integrates easily into CI/CD pipelines.

---

Quick Start

Install

pip install skill-optimizer

Scaffold a skill project

skill-optimize init my-skill

This creates:

my-skill/
├── SKILL.md              # Your skill definition (editable)
├── skill.yaml            # Skill metadata and config
└── tests/
    └── test_cases.yaml   # Benchmark test cases

Compress a skill

skill-optimize compress my-skill/SKILL.md --strategy all

Output a compressed version with token savings reported:

Original:  1,847 tokens
Compressed: 612 tokens
Savings:    66.9%
Quality:    97.2% (estimated)

Benchmark against test cases

skill-optimize benchmark my-skill/ --model gpt-4o

Runs the skill through test cases and scores output quality on a 0-100 scale.

Full optimization loop

skill-optimize optimize my-skill/ --rounds 5 --min-quality 90

Iteratively compresses and benchmarks, stopping when quality drops below 90 or max rounds are reached.

---

Compression Strategies

Strategy	Description	Typical Savings
whitespace	Remove excess blank lines, normalize indentation	5-10%
deduplication	Detect and remove repeated instructions or examples	10-20%
synonym	Replace verbose phrases with concise equivalents	5-15%
example_summary	Condense lengthy examples into essential patterns	15-25%
structural	Merge adjacent sections, remove redundant headings	10-20%

Use --strategy all to apply all strategies in optimal order, or target specific strategies with --strategy whitespace,dedup.

---

Testing

pip install pytest && pytest tests/ -v

---

Ecosystem

Skill Optimizer is part of a growing ecosystem of tools for building production AI agents:

Project	Description
claude-marketing-kit	Claude Marketing Skills + Python engine — copy, CRO, analytics, content, email, social, brand (no API keys)
claude-seo-kit	Claude SEO Skills + Python engine — audits, schema, sitemap, hreflang, GEO (no API keys)
agent-skill-kit	Define, version, and share reusable agent skills
agent-harness	Filesystem-first agent runtime with CLI and API
fastapi-ai-kit	FastAPI boilerplate for AI-powered applications
agent-memory-kit	Persistent memory and context management for agents
agent-security-kit	Input validation, output filtering, and guardrails
awesome-mcp-servers	Curated list of Model Context Protocol servers
llm-economizer	Token cost optimization proxy for LLM APIs

---

License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Built with ❤️ for the AI agent community.

If you find this useful, please consider giving it a star ⭐