Skill Authoring — как создать репу скила

Гайд по созданию репозитория скила для каталога skills/registry. Каталог читает группу gitlab.fssoft.ru/skills по требованию и определяет раскладку сам — поэтому важно класть файлы туда, где сервис их ищет.

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

Пользователь заводит новый скил, спрашивает «как оформить репу скила», как добавить скил в каталог, или сомневается между одиночной репой и монорепой.

##Шаг 1. Выбрать раскладку

Сервис определяет скилы по приоритету, точечными запросами к GitLab API — не рекурсивным сканом. Поэтому есть ровно три поддерживаемых раскладки:

1. Одиночный скил — SKILL.md в корне репы. Репа = один скил. Самое простое; бери, если скил один и не планируется второй.
2. Монорепа + манифест — несколько скилов в skills/<name>/SKILL.md плюс корневой registry.yml с явным списком путей. Рекомендуется для тематической группы скилов (пример: skills/jira).
3. Монорепа по конвенции — skills/<name>/SKILL.md без манифеста. Сервис делает один нерекурсивный листинг skills/ и берёт каждую подпапку с SKILL.md. Имя скила = имя папки.

Рекомендация: для 1 скила — раскладка 1; для 2+ — раскладка 2 (явный registry.yml надёжнее и самодокументирован).

# одиночный скил                # монорепа
repo/                            repo/
  SKILL.md                         registry.yml
  README.md                        README.md
  (scripts/ references/ …)         skills/
                                     code-review/SKILL.md
                                     pr-summary/SKILL.md

##Шаг 2. Написать SKILL.md

YAML frontmatter + тело-инструкция для агента. Обязательны только name и description; если name нет — берётся имя папки скила (монорепа) либо имя проекта.

---
name: code-review                 # обязателен; kebab-case; уникален в группе
description: |                    # обязателен; 1-3 предложения + когда применять
  Ревью кода по нашим стандартам. Использовать при PR-ревью на Go и Python.
license: MIT
version: 1.2.0
tags: [review, quality]           # для фильтра в каталоге
owners: ["redickowii"]            # ответственные
metadata:
  author: redickowii
---

# Code Review Skill

…инструкции для агента…

Рекомендации по полям:

• name — kebab-case, говорящее, без префикса skills/. Это публичный идентификатор (URL, CLI, статистика), поэтому уникален в пределах группы. При коллизии побеждает первый по алфавиту пути репы.
• description — пиши «что делает» и «когда применять» (триггеры, ключевые слова): по нему агент решает, релевантен ли скил.
• tags — для поиска/фильтра в каталоге.
• owners / metadata.author — кто отвечает и кто автор.

Рекомендации по телу:

• Структура: назначение → триггеры → пошаговый workflow → правила/ограничения.
• Команды — в блоках кода. Опасные/необратимые шаги — с подтверждением.
• Большие вспомогательные файлы клади в scripts/, references/, examples/ — скачивание (/archive) отдаёт всё поддерево скила.

##Шаг 3. registry.yml (только для монорепы)

Корневой манифест с явными путями — самый надёжный способ:

skills:
  - path: skills/code-review
  - path: skills/pr-summary
  - skills/release-notes        # короткая строковая форма тоже ок

##Шаг 4. Создать репу и запушить

# репа создаётся в группе skills; default branch — main
git init && git checkout -b main
# … разложить SKILL.md (+ registry.yml для монорепы) …
git add -A && git commit -m "Init <skill>: …"
git remote add origin https://gitlab.fssoft.ru/skills/<repo>.git
git push -u origin main

main обычно защищён (push: Maintainers, force push off). Обычный коммит идёт без проблем; для перезаписи истории нужны права Maintainer и временное снятие защиты ветки.

##Шаг 5. Проверить, что каталог увидел скил

Новый скил появляется автоматически: фоновый refresh каждые REFRESH_INTERVAL (деф. 60с), либо мгновенно по group-webhook на push. Проверка:

curl https://skills.fssoft.ru/api/skills | jq '.skills[].name'
curl https://skills.fssoft.ru/api/skills/<name> | jq

Установка пользователем (токен GitLab не нужен):

fs-skills install <name>

##Чек-лист

• Раскладка выбрана (одиночный / монорепа+манифест / монорепа по конвенции).
• SKILL.md на месте (корень или skills/<name>/).
• frontmatter: name (kebab-case, уникален) и description (что + когда).
• tags, owners, metadata.author, license заполнены.
• Для монорепы — registry.yml со всеми путями.
• README.md с таблицей скилов и командой установки.
• Запушено в main, скил виден в /api/skills.

##Правила

• Имя скила уникально в группе — проверь curl …/api/skills перед выбором.
• Не дублируй один скил в двух репах: при коллизии имён каталог берёт один, второй «теряется». Старую репу — deprecate/удалить.
• Не клади секреты в SKILL.md/скрипты — репы приватные, но скил скачивается пользователями во все агенты.