skill-suggester

name	skill-suggester
description	Skill recommendation for AI agents from the agent-skills library. Reads the master catalog index.json (default ~/Projects/agent-skills/index.json, override with env AGENT_SKILLS_INDEX or --index), scores triggers and descriptions, returns top-5 with relevance plus up to 3 combos for multi-step tasks. Supports ad-hoc apply: prints SKILL.md paths so the agent can read and apply a skill's instructions directly even if it is not installed. Triggers: 'какой скилл использовать', 'skill suggestion', 'suggest skill', 'рекомендовать скилл', 'recommend a skill', 'which skill', 'подобрать навык'.
license	MIT
metadata	{"author":"best","version":"1.1.0"}
compatibility	Requires Python3; reads index.json
when_to_use	Use when user doesn't know which skill to use: 'which skill', 'suggest skill', 'recommend a skill', 'какой скилл использовать', 'подобрать навык', 'рекомендовать скилл'. Example: 'What skill should I use for SEO?' / 'Какой скилл взять для репозитория?'.

Skill Suggester — подбор скиллов по задаче

Помощник, который по свободному описанию задачи/намерения пользователя подсказывает, какой скилл из библиотеки agent-skills использовать и как их комбинировать.

When to use

Загружай этот скилл, когда пользователь не знает, какой скилл применить:

• «какой скилл использовать для …», «какой skill подойдёт», «что выбрать»
• «подбери инструмент / команду / навык под задачу»
• «рекомендуй скилл», «suggest skill», «skill suggestion»
• задача сформулирована свободным текстом, но без явного указания скилла
• нужно понять, какие скиллы можно объединить в цепочку для многоэтапной работы

Do NOT use

• Когда задача уже явно называет скилл («сделай презентацию» → presentation-maker, «сгенерируй тестовые картинки» → test-graphics) — загружай его напрямую.
• Когда пользователь просит выполнить работу, а не выбрать инструмент.
• Для подбора инструментов вне библиотеки (это не каталог внешних утилит).

What this skill does

Вход: описание задачи свободным текстом (одна строка или фраза).

Выход:

1. Список подходящих скиллов с релевантностью (score) и кратким «почему использовать».
2. Не больше 3 комбо — последовательностей скиллов для многоэтапной задачи (например, code-review → commit-message-writer → github-repo-hygiene).

How to work

1. Спросить задачу. Если пользователь не дал описание — уточни, что он хочет сделать (одним вопросом). Если описание есть — переходи к шагу 2.
2. Прочитать базу. Открой index.json в корне репозитория и прочитай у каждого скилла поля name, triggers, description, category. При необходимости загляни в skills/<name>/SKILL.md для деталей.
3. Сопоставить. Сравни запрос с триггерами и описаниями скиллов. Учти синонимы и перефразировки (RU/EN). Определи категорию задачи (repository / media / social / code / data) и отметь скиллы этой категории.
4. Выдать рекомендацию. Отсортируй по релевантности, выведи топ-3–5: rank. skill-name (score) — почему использовать. Если задача многоэтапная — предложи до 3 комбо-цепочек.

Можно автоматизировать шаги 2–4 скриптом:

python3 scripts/skill_suggest.py "нужно описать репозиторий"
python3 scripts/skill_suggest.py "сгенерируй презентацию" --combo

On-demand loading (ad-hoc apply)

Скилл — это просто набор инструкций в SKILL.md. Если нужного скилла нет в системе, его можно применить ad-hoc: прочитать его SKILL.md из мастер-каталога и выполнить инструкции напрямую — формальная установка не требуется.

Мастер-каталог: ~/Projects/agent-skills (локальный клон) или https://github.com/bestdeejay-design/agent-skills (GitHub raw).

Скрипт skill_suggest.py после выдачи топа печатает путь к SKILL.md каждого подходящего скилла. Если скилл не установлен:

1. Прочитай skills/<name>/SKILL.md из мастер-каталога.
2. Проверь триггеры и «Do NOT use» — убедись, что скилл действительно подходит.
3. Выполни инструкции скилла в текущей сессии.

Если мастер-каталог в другом месте — задай его через env AGENT_SKILLS_INDEX или флаг --index.

Scoring

Взвешивание релевантности (по убыванию приоритета):

1. Keyword match (вес 3) — точное совпадение триггера скилла с запросом (фраза или слово). Самый сильный сигнал.
2. Category match (вес 2) — задача попадает в категорию скилла (code / media / repository / social / data).
3. Description match (вес 1) — совпадение отдельных слов запроса со словами описания скилла. Слабый, но полезный сигнал для перефразировок.

Скрипт skill_suggest.py реализует keyword (3) и description (1); категорийный бонус агент добавляет вручную при анализе.

Examples

Пример 1. Запрос: «нужно описать репозиторий, чтобы его можно было публиковать» → github-repo-hygiene (триггер «описание репозитория», категория repository). Обоснование: скилл проверяет README, LICENSE, CONTRIBUTING, topics и GitHub Pages.

Пример 2. Запрос: «сделай доклад по итогам квартала» → presentation-maker (триггер «сделай доклад», категория media). Обоснование: генератор презентаций с авто-лейаутами и .pptx.

Пример 3. Запрос: «проверь код, оформи коммит и подготовь репозиторий к релизу» → комбо: code-review → commit-message-writer → github-repo-hygiene. Обоснование: три этапа — анализ кода, осмысленный коммит, публикационная гигиена.

Constraints

• Не выдумывай несуществующие скиллы. Рекомендуй только те, что есть в index.json / папке skills/ репозитория.
• База скиллов — только этот репозиторий (agent-skills), не внешние каталоги.
• Не больше 3 комбо в ответе; каждое комбо — 2–3 скилла в логичном порядке.
• Если ни один скилл не подходит — честно скажи об этом и предложи переформулировать задачу, а не подгоняй нерелевантный скилл.