AgentSkillsCN

skill-audit

审计SKILL.md与qa_agent.md，重点关注冗余、重复以及有害模式（如“不修复”、过度膨胀的模板）。可用于优化AI部署流程，降低Token消耗。请勿用于文档审计——此类工作应交由/doc-lint完成。

SKILL.md
--- frontmatter
name: skill-audit
description: Аудит SKILL.md и qa_agent.md на раздутость, дублирование, вредные паттерны ("НЕ ИСПРАВЛЯТЬ", раздутые шаблоны). Используй для оптимизации AI-сетапа и снижения токен-расхода. Не используй для аудита документации — для этого /doc-lint.
allowed-tools: "Read Write Edit Glob Grep Bash(wc*)"
agent: agents/auditor.md
context: fork

Skill & Agent Audit

Аудит AI-инструкций на эффективность: находит раздутость, дублирование, вредные паттерны.

Перед началом

Прочитай:

  1. •.claude/qa_agent.md и .claude/agents/auditor.md
  2. •.claude/skills/init-skill/references/validation-checklist.md — пороги строк и обязательные секции
  3. •.claude/skills/init-skill/references/yaml-reference.md — правила YAML frontmatter

Когда использовать

  • •После создания нового скилла через /init-skill
  • •При подозрении что скилл тратит слишком много токенов
  • •Периодически (раз в спринт) для всех скиллов
  • •После обновления CLAUDE.md или qa_agent.md

Входные данные

ПараметрОбязательностьОписание
ScopeОпциональноПуть к конкретному скиллу или "all". По умолчанию — все скиллы

Алгоритм (9 проверок)

Verbosity Protocol

Structured Output Priority: Весь analysis идёт в артефакт (MD/HTML), не в чат.

Chat output (ограничения):

  • •Brief Summary: max 5 строк (что нашли, сколько, итог)
  • •Полный отчёт: 📊 Полный отчёт: {path} + открыть файл

Iterative steps: Не выводить прогресс по каждому файлу. Checkpoint только при:

  • •Phase transition (Фаза N → Фаза N+1)
  • •Blocker обнаружен
  • •Завершение (SKILL COMPLETE)

Tools first:

  • •Grep → table → report, без "Now I will grep..."
  • •Read → analyze → report, без "The file shows..."

Post-Check: Inline перед SKILL COMPLETE (5-7 строк checklist), не отдельный файл.

Check 0: Standards Drift

Проверь, что пороги в этом SKILL.md совпадают с init-skill/references/validation-checklist.md:

  • •Лимит строк SKILL.md (сейчас в чеклисте: ≤500)
  • •Обязательные поля YAML frontmatter
  • •Обязательные секции контента

Если расхождение найдено → ERROR «Standards Drift: {поле} в audit={X}, в checklist={Y}». Рекомендация: обновить пороги в skill-audit/SKILL.md по чеклисту.

Check 1: Line Count

Для каждого SKILL.md — wc -l. Порог берётся из init-skill/references/validation-checklist.md (секция «Структура», поле SKILL.md ≤ N строк):

Порог (по чеклисту)Severity
≤ thresholdOK
threshold+1 … threshold×1.1WARNING
> threshold×1.1CRITICAL

Текущий threshold по чеклисту: 500 строк.

Для qa_agent.md: OK ≤200, WARNING 201-300, CRITICAL >300.

Check 1a: YAML Compliance

Для каждого SKILL.md сверь frontmatter с правилами из init-skill/references/yaml-reference.md:

  • •name в kebab-case, совпадает с именем папки, без "claude"/"anthropic"
  • •description содержит три части: Что / Когда / Когда НЕ
  • •description < 1024 символов, без XML-символов (<, >), однострочный
  • •Если agent: присутствует — referenced файл существует

Severity: ERROR (отсутствует обязательное поле), WARNING (нарушение формата description).

Check 1b: Verbosity Protocol

Grep: ## Verbosity Protocol, SILENT MODE, NO CHAT TABLES в SKILL.md файлах.

  • •Severity: CRITICAL (если отсутствует)
  • •Почему: Агенты без этого протокола замусоривают чат, выводят промежуточные таблицы и списки, тратят токены на болтовню
  • •Исключение: Если у скилла есть agent: в frontmatter — проверь Verbosity Protocol в файле агента (agents/{name}.md). Дублировать в SKILL.md не нужно — флагать только если отсутствует и в SKILL.md, и в агенте.
  • •Рекомендация: Добавить Verbosity Protocol в файл агента (не в SKILL.md)

Check 2: Self-Review Protocol (раздутый)

Grep: Self-Review, self_review, _self_review.md, шаблоны отчётов с Scorecard.

  • •Severity: WARNING (только если self-review шаблон >50 строк или не содержит Scorecard)
  • •Почему: раздутые шаблоны тратят токены; компактные Scorecard — полезный инструмент трекинга
  • •Рекомендация: оптимизировать шаблон до ≤50 строк с обязательным Scorecard
  • •Исключения:
    • •*_self_review.md файлы с Scorecard — ценные артефакты трекинга прогресса. Не флагать

Check 3: "НЕ ИСПРАВЛЯТЬ" Instruction

Grep: НЕ ИСПРАВЛЯТЬ, не исправляй, только анализ — в контексте review/check секций.

  • •Severity: CRITICAL
  • •Почему: AI документирует проблемы вместо исправления
  • •Рекомендация: заменить на "ИСПРАВЬ КОД/аудит, перекомпилируй"

Check 4: Tech Stack Duplication

  1. •Прочитай CLAUDE.md → найди Tech Stack
  2. •Grep в каждом SKILL.md по ключевым словам стека (Ktor, Jackson, Kotest, etc.)
  3. •Если SKILL.md содержит полную таблицу стека (≥4 строки с |) → дублирование
  • •Severity: WARNING
  • •Рекомендация: заменить таблицу на Стек LOCKED в CLAUDE.md → Tech Stack + дополнения

Check 5: Code Examples >50 Lines

Найти code blocks (kotlin, python, etc.) в SKILL.md. Подсчитать строки в каждом.

  • •Severity: WARNING (если блок >50 строк)
  • •Рекомендация: вынести в references/examples.md, оставить 3-4 строки спецификации + ссылку

Check 6: Decorative Code Blocks

Найти ``` блоки которые НЕ содержат код:

  • •

    Нет language identifier

  • •

    Содержимое = текст с emoji/bullet points/markdown formatting

  • •

    Severity: INFO

  • •

    Рекомендация: заменить на обычные списки/bold text

Check 7: Anti-Patterns Verbosity

Найти секции BANNED/Anti-Patterns. Подсчитать строки и парные Bad/Good блоки (❌/✅ с кодом).

  • •Severity: WARNING (если пар >3 и строк >30)
  • •Рекомендация: заменить на однострочники, подробности → qa-antipatterns/*.md или skill-specific references/

Check 8: Cross-Reference Staleness

  1. •Собрать ссылки из qa_agent.md на секции/паттерны скиллов
  2. •Проверить что referenced секции существуют в текущих SKILL.md
  3. •Проверить Skill Completion Protocol на ссылки удалённых паттернов
  • •Severity: ERROR
  • •Рекомендация: обновить qa_agent.md

Check 9: Rarely-Used Sections Inline

Найти секции с:

  • •

    "промпты для кастомизации/генерации/адаптации"

  • •

    Мета-инструкции для пользователя (не для AI при выполнении)

  • •

    Контент используемый 1 раз за проект, но загружаемый каждый вызов

  • •

    Severity: INFO

  • •

    Рекомендация: вынести в references/

Формат отчёта

Записать полный отчёт в audit/skill-audit-report.md (таблица находок + Summary).

В чат вывести только:

code
📊 Skill Audit: {N} CRITICAL, {N} WARNING, {N} INFO → audit/skill-audit-report.md

Severity Model

SeverityЧто ловит
CRITICAL"НЕ ИСПРАВЛЯТЬ", SKILL.md >500 строк
ERRORStale cross-references в qa_agent.md
WARNINGSelf-Review Protocol (раздутый >50 строк), Tech Stack дублирование, код >50 строк inline, Anti-Patterns >30 строк, 300-500 строк
INFODecorative ``` блоки, rarely-used sections inline

Post-Audit Check (в чат, НЕ создавай файл)

  • • Все скиллы в scope проверены?
  • • Line counts верифицированы через wc -l?
  • • Нет false positives (контекст каждого finding проверен)?
  • • Рекомендации конкретные (что → куда)? ← каждая рекомендация называет конкретный файл и действие, не "улучшить" или "пересмотреть"

Если нашёл ошибку в аудите → исправь. НЕ создавай *_self_review.md.

Завершение

После Post-Audit Check — напечатай блок SKILL COMPLETE (формат в qa_agent.md § Skill Completion Protocol).