Skill Optimizer
hqhq1025/skill-optimizerИнструмент для анализа SKILL.md-файлов: сочетает статический анализ с разбором реальных сессий. Измеряет частоту срабатываний, реакцию пользователя, покрытие воркфлоу и токен-экономику. Совместим с Claude Code, Codex и любым агентом стандарта Agent Skills.
Установка
git clone https://github.com/hqhq1025/skill-optimizer.gitREADME
Skill Optimizer
Диагностика и оптимизация ваших Agent Skills (файлов SKILL.md) с использованием реальных данных сессий и статического анализа на основе исследований. Формирует приоритизированный отчёт с исправлениями уровней P0/P1/P2.
Работает с Claude Code, Codex и любым агентом, поддерживающим открытый стандарт Agent Skills. Автоматически определяет платформу и сканирует нужные пути.
Большинство аудиторов скиллов выполняют только статические проверки SKILL.md. Этот инструмент также анализирует реальные транскрипты сессий: измеряет частоту срабатываний, удовлетворённость пользователя, завершённость воркфлоу и пропущенные срабатывания — затем оценивает каждый скилл по составной 5-балльной шкале.
Что делает инструмент
6 оцениваемых измерений (взвешенно входят в составную оценку):
| Измерение | Что оценивается |
|---|---|
| Trigger Rate | Как часто скилл реально вызывается по сравнению с тем, как часто должен? |
| User Reaction | Принимает, исправляет или отклоняет пользователь скилл после вызова? |
| Workflow Completion | Насколько далеко выполнение продвигается по заданным шагам скилла? |
| Static Quality | 14 проверок: безопасность YAML, соответствие CSO, позиция информации, количество слов и др. |
| Undertrigger | Пропущенные срабатывания — скилл был нужен, но не вызван |
| Token Economics | Экономичность и соответствие уровням progressive disclosure |
3 качественных измерения (отображаются в отчёте, но не влияют на оценку):
| Измерение | Что оценивается |
|---|---|
| Overtrigger | Ложные срабатывания — скилл вызван, но пользователь этого не хотел |
| Cross-Skill Conflicts | Пересечение триггерных ключевых слов и противоречивые инструкции между скиллами |
| Environment Consistency | Нерабочие пути к файлам, отсутствующие CLI-инструменты, несуществующие директории |
Установка
Скопируйте команду ниже и вставьте её прямо в чат агента — установка произойдёт автоматически:
Claude Code
Install the skill-optimizer skill from https://github.com/hqhq1025/skill-optimizer
Codex
Install the skill-optimizer skill from https://github.com/hqhq1025/skill-optimizer into ~/.codex/skills/
Другие агенты (Cursor, OpenCode, Gemini CLI и др.)
Install the skill-optimizer skill from https://github.com/hqhq1025/skill-optimizer into ~/.agents/skills/
# Claude Code
git clone https://github.com/hqhq1025/skill-optimizer.git /tmp/skill-optimizer
cp -r /tmp/skill-optimizer/skills/skill-optimizer ~/.claude/skills/
rm -rf /tmp/skill-optimizer
# Codex
git clone https://github.com/hqhq1025/skill-optimizer.git /tmp/skill-optimizer
cp -r /tmp/skill-optimizer/skills/skill-optimizer ~/.codex/skills/
rm -rf /tmp/skill-optimizer
# Shared (любой агент)
git clone https://github.com/hqhq1025/skill-optimizer.git /tmp/skill-optimizer
cp -r /tmp/skill-optimizer/skills/skill-optimizer ~/.agents/skills/
rm -rf /tmp/skill-optimizerИспользование
/optimize-skill # Сканировать все скиллы
/optimize-skill my-skill # Один скилл
/optimize-skill skill-a skill-b # Несколько скиллов
Скилл формирует диагностический отчёт, включающий:
- Сводную таблицу — все скиллы с оценками одним взглядом
- P0 Fixes — блокирующие проблемы, требующие обязательного устранения
- P1 Improvements — улучшения пользовательского опыта
- P2 Optimizations — опциональные доработки
- Диагностику по каждому скиллу — все 8 измерений для каждого скилла
Анализ сессий на нескольких платформах
Оптимизатор автоматически определяет доступные платформы и сканирует данные сессий со всех из них:
| Платформа | Путь к скиллам | Путь к данным сессий |
|---|---|---|
| Claude Code | ~/.claude/skills/ | ~/.claude/projects/**/*.jsonl |
| Codex | ~/.codex/skills/ | ~/.codex/sessions/**/*.jsonl |
| Shared | ~/.agents/skills/ | — |
Научная база
Измерения анализа основаны на рецензируемых исследованиях:
| Исследование | Ключевой вывод | Применение |
|---|---|---|
| Memento-Skills (2026) | Скиллы как структурированные файлы требуют точной маршрутизации; нераспознанные скиллы не могут самосовершенствоваться через цикл обучения read-write | Обнаружение undertrigger, оценка накопленного риска |
| MCP Description Quality (2026) | Хорошо написанные описания дают 72% точности выбора инструмента против 20% у случайного базового уровня (улучшение в 3,6×) | Проверки качества описаний, предложения по переработке |
| Lost in the Middle (Liu et al., TACL 2024) | Внимание LLM следует U-образной кривой — контент в середине игнорируется | Проверка позиции критически важной информации |
| Prompt Format Impact (He et al., 2024) | Только изменение формата вызывает разброс производительности 9–40% | Статический анализ качества |
| IFEval (Zhou et al., 2023) | LLM испытывают трудности с промптами, содержащими множество ограничений | Проверка количества условий срабатывания |
| Meincke et al. (2025) | Директивы убеждения дают непоследовательный эффект в разных моделях | Рекомендации по плотности MUST/NEVER |
Как это работает
Определение целевых скиллов (сканирование ~/.claude/skills/, ~/.codex/skills/, ~/.agents/skills/)
↓
Сбор данных сессий (автоопределение платформы, сканирование JSONL-транскриптов)
↓
Запуск 8 измерений анализа (6 оцениваемых + 3 качественных)
↓
Вычисление составных оценок (взвешенное среднее 6 оцениваемых измерений)
↓
Вывод отчёта с приоритизированными исправлениями P0/P1/P2
Оцениваемые измерения (взвешенное среднее):
- Trigger rate: 25%
- User reaction: 20%
- Workflow completion: 15%
- Static quality: 15%
- Undertrigger: 15%
- Token economics: 10%
Качественные измерения (overtrigger, cross-skill conflicts, environment consistency) отображаются с примерами, но не влияют на числовую оценку.
Совместимость
Работает с любым агентом, поддерживающим открытый стандарт Agent Skills:
- Claude Code
- Codex
- Cursor
- OpenCode
- Gemini CLI