agent-skill-linter

Linter для репозиториев agent-skill: сверяет SKILL.md со спецификацией, а затем проверяет готовность к публикации по файлу LICENSE, бейджам в README, CI-пайплайну, структуре кода и стилю Python-скриптов. Рассчитан на кросс-платформенную экосистему Agent Skills с реестром на agentskills.io - один и тот же набор навыков работает в Claude Code, Cursor, Gemini CLI, Amp, Roo Code и Copilot.

Позиционирование: этот linter служит входным фильтром, определяющим, "готов ли навык к публикации в реестре", а не инструментом проверки корректности в рантайме. Ближайшие аналоги по формату - markdownlint или actionlint: предметно-ориентированный lint с автоматическим исправлением простых недочётов.

Что проверяется (~21 правило)

Уровни важности: Error / Warning / Info; для части предупреждений доступен флаг --fix.

Спецификация и метаданные

• Соответствие SKILL.md спецификации (через эталон skills-ref) - Error
• Наличие и корректность поля author во frontmatter - Warning, с автоисправлением

Лицензирование

• Файл LICENSE присутствует, содержит лицензию Apache-2.0 или MIT и указывает текущий год - Warning, частично исправляется автоматически

Документация

• В README есть бейджи CI, лицензии и совместимости с Agent Skills - Warning, с автоисправлением
• Присутствует раздел с инструкцией по установке - Warning, с автоисправлением
• Раздел по использованию содержит примеры промптов - Warning
• Подраздел по работе через CLI - Info

Инфраструктура

• В .github/workflows/ настроен хотя бы один рабочий процесс CI - Warning, с автоисправлением

Качество кода

• Единообразные шаблоны вызова Python-скриптов (в стиле uv)
• Файлы шаблонов и справочников разложены по ожидаемым путям
• Структура репозитория изолирует навык
• Зоны ответственности между README и SKILL.md чётко разделены

Продвинутые правила

• SKILL.md укладывается в 500 строк - Info (экономия контекстного окна)
• Входные скрипты используют встроенные метаданные зависимостей по PEP 723 - Warning
• Рабочие процессы CI включают шаг семантического анализа и триажа - Info

Установка

Универсальная однострочная команда использует инсталлятор skills, который становится стандартом де-факто для пакетов навыков (его же использует impeccable):

npx skills add William-Yeh/agent-skill-linter

Команда сразу раскладывает навык по директориям всех поддерживаемых сред. Описана и ручная установка:

# Claude Code
cp -r skill/ ~/.claude/skills/agent-skill-linter/

# Cursor
cp -r skill/ .cursor/skills/agent-skill-linter/

После установки навык обучает агента запускать linter по текстовым запросам:

"Lint the skill in this directory for publishing readiness." "Check ~/projects/my-skill for spec compliance and fix any issues."

Использование через CLI

Точку входа на Python можно запускать и напрямую без среды агента:

./scripts/skill-lint.py check ./my-skill
./scripts/skill-lint.py check . --fix
./scripts/skill-lint.py check ./my-skill --format json

Вывод в формате JSON сделан специально для того, чтобы агент мог передать результаты lint'а обратно в свой цикл и обработать их.

Зачем навыкам детерминированный linter

Тот же аргумент, что и для детектора в impeccable: когда LLM оценивает вывод другой LLM, сказывается смещение из общих обучающих данных. Поэтому дешёвое и понятное правило справляется с задачей "не забыт ли файл LICENSE" надёжнее умного, но размытого судьи. Набор из 21 правила намеренно невелик: это чеклист готовности к публикации, а не планка качества. Любые субъективные оценки должны происходить до запуска linter'а.

Статус

Проекту три месяца (создан 2026-02-12), 2 звезды, 1 форк, один автор (William-Yeh), 4 релиза вплоть до v0.11.0 (апрель 2026 года), 0 открытых issue. Высокая частота релизов 0.x говорит об активной поддержке; скромное число звёзд - обратный сигнал. Экосистема кросс-платформенных навыков пока мала, поэтому полезный инструмент заметят, скорее всего, только тогда, когда наберёт популярность проверяемый им реестр (agentskills.io).

Внесён в watchlist - повторная проверка 2026-08-02. Что отслеживать: распространение реестра, появление второго контрибьютора, выход за рамки навыков авторства William-Yeh.

Ограничения

• Глубокие проверки (PEP 723, запуск через uv) работают только для навыков на Python. Для пакетов на TypeScript/JS проверяются правила по документации, лицензии и CI, но не языковые особенности.
• Завязан на актуальность спецификации skills-ref: если реестр сменит владельца или разделится, linter'у придётся догонять изменения.
• Пока нет интеграции с редакторами (нет LSP, нет pre-commit хука в репозитории); входными точками остаются только CLI и промпты к агенту.
• Две звезды говорят о размере экосистемы, а не о качестве: инструмент вполне может работать нормально, просто оставаясь в узкой нише.

См. также

• mcp-vs-skills - контекст: что вообще такое "навык агента" и почему важна их переносимость.
• impeccable - тот же шаблон установки через npx skills add ..., та же философия детерминированного lint'а, но другая область (клише в визуальном дизайне).
• claude-defuddle - пример узкоспециализированного навыка для Claude Code, на который рассчитан этот linter.
• clippy-stricter-config - аналогичный подход к "проверке готовности к публикации через lint-конфигурации" в Rust.

Репозиторий

github.com/William-Yeh/agent-skill-linter · 2★ · Apache-2.0 · Python · v0.11.0

Источник: agent-skill-linter-readme.