AI Vibe Craft
← Назад к AI Vibe News

Редакция 13 июня 2026 г.

Разборы

skillscore: CLI, который ставит оценку SKILL.md вашего AI-агента по шкале 0–100

skillscore: CLI, который ставит оценку SKILL.md вашего AI-агента по шкале 0–100.

skillscore — открытый Dart-инструмент, который статически проверяет файлы навыков агентов и выставляет балл от 0 до 100. Он сравнивает SKILL.md с authoring guides Claude, Codex и Antigravity, работает без сети и даёт детерминированный результат — то, что можно встроить в CI рядом с обычным линтингом кода.

Почему размытый SKILL.md дороже, чем его отсутствие

У агента поля name и description из каждого подключённого skill постоянно живут в context window. Размытое описание не исчезает после одного промпта — оно «налогует» каждый следующий запрос: модель тратит токены на догадки, а не на задачу. Автор skillscore формулирует крайний случай так: vague skill хуже, чем отсутствие skill вовсе.

Формат общий для экосистемы agent skills: папка с SKILL.md (YAML frontmatter с name и description плюс Markdown-тело), опционально references/, examples/, scripts/, assets/. Такой же файл читают Claude Code, Codex, Antigravity, Gemini CLI и Cursor — skillscore заявлен как name-agnostic: имя папки, имя файла и поле name могут не совпадать, проверяется содержимое спеки.

Проверка схемы frontmatter отвечает на вопрос «валидно ли», markdown-linter — на «красиво ли», LLM-review — на «звучит ли разумно». Последний не детерминирован и плохо годится как gate в CI. skillscore занимает середину: quality score, ссылка на конкретное правило из гайда и офлайн-прогон без inference.

Двадцать четыре правила, семь категорий и буквенный грейд

CLI разбирает SKILL.md статически и возвращает число 0–100, буквенный грейд и список findings — для каждой находки указаны id правила и исходный authoring guide.

Гайды сведены в 24 проверяемых правила в семи категориях A–G:

  • A — Frontmatter validity — delimiters ---, формат name, наличие description
  • B — Description quality — what/when, third person, front-loaded triggers, boundary clause
  • C — Conciseness — длина body, отсутствие «explainer bloat», длинные цепочки «or»
  • D — Structure — progressive disclosure, ссылки на один уровень, TOC в длинных references
  • E — Instruction quality — anti-patterns, workflow checklist, feedback loop, code examples
  • F — Content hygiene — устаревающие даты, forward-slash paths, consistent terminology
  • G — Safety & scripts — штраф до −15, если skill поставляет scripts/commands без документации или секции Safety

Сто баллов распределены по категориям A–F; G — только штраф при наличии scripts или terminal commands. Грейды: A — 90–100, B — 80–89, C — 70–79, D — 60–69, F — ниже 60.

На pub.dev в примере skill csv-to-xlsx фиксируется 72/100, Grade C с предупреждением B2_description_when — в description нет trigger clause «when to use». В посте на Dev.to для реального skill команды Flutter flutter-add-widget-test/SKILL.md указаны 90/100, Grade A; находки уровня WARNING (E1_anti_patterns) и INFO (B5_boundary_clause). Даже при кривом frontmatter CLI не падает: сообщает ошибки категории A, остальные применимые правила всё равно выполняются, score выдаётся.

Детали любого правила можно вытянуть командами skillscore explain <rule-id> или skillscore rules.

--target: Claude, Codex, Antigravity и universal

Флаг --target принимает claude, codex, antigravity или universal (значение по умолчанию). Профиль universal — «портативный skill должен проходить везде»; отдельные правила привязаны к вендорам:

Правило Targets Источник гайда
B4_frontloaded_triggers — keywords в первых ~60 символах description codex, universal Codex
B5_boundary_clause — boundary «do not use» antigravity, universal Antigravity
G1_safety_section — scripts/commands требуют секции Safety antigravity, universal Antigravity
A3_name_reserved_words — severity error для claude, info для остальных все Anthropic

При --target claude исключается Codex-специфичное правило B4; score нормализуется обратно к шкале 0–100, чтобы сравнение между targets оставалось сопоставимым. Каждая находка цитирует source guide — удобно, когда один репозиторий skills должен ездить между Claude Code и Codex с разными ожиданиями к description.

Оффлайн-линтер в CI: от установки до SARIF

Установка через pub.dev:

dart pub global activate skillscore

Типовой прогон — один файл или дерево skills в monorepo:

skillscore path/to/SKILL.md
skillscore path/to/skills/
skillscore my-skill/ --target claude

Для автоматизации:

skillscore skills/ --format json
skillscore skills/ --min-score 80 --no-color
skillscore skills/ --format sarif

Флаг --min-score (0–100) даёт non-zero exit, если skill ниже порога; --strict превращает warnings в errors; --quiet оставляет только итоговую строку score. Exit codes: 0 — порог пройден; 1 — ниже --min-score или срабатывание --strict; 2 — usage error (bad path, invalid flag). Формат SARIF 2.1.0 позволяет подключить вывод к code scanning и аннотациям в PR — тот же паттерн, что для статического анализа кода, только цель — agent skills.

Пакет на pub.dev — версия 0.1.1, лицензия Apache-2.0; исходники — в репозитории sayed3li97/skillscore. В материале на Dev.to от 12 июня 2026 автор отмечает ранний релиз v0.1.0 и стабильность rubric; публичный Dart API (package:skillscore/skillscore.dart) экспортирует SkillParser, Scorer, RuleRegistry, Target.universal для встраивания в свои инструменты.

Что дальше: roadmap без обещаний релиза

В том же посте перечислены планы — больше vendor targets, autofix для механических находок, GitHub Action wrapper. Это заявленный roadmap, а не фичи «уже в проде»; сегодня ценность — детерминированный score и cited sources offline.

Для команд, которые формализуют поведение агентов через markdown-спеки вместо разовых промптов в чате, skillscore — редкий случай инструмента, где качество SKILL.md измеряется теми же критериями, что прописаны в гайдах Anthropic, OpenAI и Google Antigravity — без облачного inference и с выходом, пригодным для CI.

Источники