opencode-config/.opencode/skills/repo-readme/SKILL.md

name	description
repo-readme	Use when creating or updating README.md for any slaid098 repository. Calls create-readme tool for deterministic structure with delimiter tags for slaid098.dev showcase. Also when user says "оформи README", "обнови описание репо", "readme template", "базовая структура readme".

Repo README

Стандартизация README.md во всех репозиториях slaid098 через тулзу create-readme. Тулза гарантирует структуру (разделители, Support block, Quick Start, language switcher). Скилл даёт контекст: когда вызывать тулзу и какие параметры передавать.

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

• Новый репо → create-readme (mode: create) — генерирует стандартизированный README с нуля.
• Проверка существующего README → create-readme (mode: validate) — проверяет, что структура соответствует стандарту витрины.
• После ручных правок README → всегда validate. Любая правка руками агента (через Edit/Write) может нарушить разделители — после правок обязательна валидация.

Не генерируй README вручную через Write — структура критична для парсинга витриной. Только через тулзу create-readme.

2. Tier system

Тулза принимает параметр tier:

• flagship — флагманские проекты (Anti-Detect MCP, Mobile Whisper и т.п.). Полный набор параметров: demo_gif (демо-гифка), custom_sections, telegram. Используется для заметных проектов на витрине.
• utility (default) — бытовые утилиты. Минимальный набор: problem / solution (EN+RU), quick_start. demo_gif игнорируется.

Выбор tier влияет только на блок demo_gif после EN-разделителей. Остальная структура одинакова для обоих tier'ов.

3. GitHub metadata (отдельный шаг, НЕ в тулзе)

create-readme отвечает только за файл README.md. Метаданные репозитория настраиваются отдельно через gh repo edit (это bash, не тулза):

• Описание: gh repo edit --description "короткое описание"
• Topics для поиска: gh repo edit --add-topic topic1 --add-topic topic2
• Social preview image — через настройки GitHub UI (не CLI).

Метаданные не дублируют README — они для карточки репо на GitHub и поиска.

4. Workflow

1. create-readme (mode: create) → генерирует README с гарантированной структурой.
2. Ручные правки если нужно (агент редактирует файл напрямую через Edit) — например, расширить custom_sections, поправить формулировки.
3. create-readme (mode: validate) → проверяет, что структура не нарушена.
4. Если validate fails → фикс нарушения → re-validate. Цикл пока не пройдёт.

Локальный режим (по умолчанию): тулза пишет в file_path (default README.md) через fs.writeFileSync. Удалённый режим: передай repo (owner/name) — тулза сделает PUT через gh api repos/{owner}/{repo}/contents/README.md с base64-контентом и SHA.

5. Зачем разделители (контекст для агента)

Витрина slaid098.dev скачивает raw README.md из каждого репо и извлекает фрагмент между разделителями:

• <!-- summary-en:start --> ... <!-- summary-en:end --> — английский блок для карточки.
• <!-- summary-ru:start --> ... <!-- summary-ru:end --> — русский блок.

Поэтому структура README должна быть гарантирована тулзой, а не агентом. Агент может менять текст внутри разделителей, но не должен удалять/двигать сами разделители. validate ловит такие нарушения.

6. Шаблон README (reference)

Тулза create-readme генерирует ровно эту структуру (параметры подставляются):

# 🚀 {repo_name}
> {tagline}

[English](#-english) | [Русский](#-русская-версия)

---

## 🇬🇧 English

<!-- summary-en:start -->
### 🔴 Problem
{problem_en}

### 🟢 Solution
{solution_en}
{custom_sections_en — доп. секции, если переданы}
<!-- summary-en:end -->
{demo_gif строка, только если tier=flagship}

### ⚡ Quick Start
\`\`\`bash
git clone https://github.com/slaid098/{repo_name}.git
{quick_start}
\`\`\`

---

## 🇷🇺 Русская версия

<!-- summary-ru:start -->
### 🔴 Проблема
{problem_ru}

### 🟢 Решение
{solution_ru}
{custom_sections_ru — доп. секции, если переданы}
<!-- summary-ru:end -->

### ⚡ Быстрый старт
\`\`\`bash
git clone https://github.com/slaid098/{repo_name}.git
{quick_start}
\`\`\`

---

## 💬 Support & Contact / Поддержка и связь

Have questions, need custom features, or want to support this project?  
👉 **[Visit Support & Contact Page](https://slaid098.dev/support)**
{telegram строка, если передан}

validate проверяет: наличие обоих EN/RU разделителей, непустой контент между ними, ссылку slaid098.dev/support, секции Quick Start (EN) и Быстрый старт (RU), language switcher [English] / [Русский].

7. Независимость от repo-init

• Скилл repo-init создаёт пустой README.md как часть инициализации репо.
• repo-readme (через тулзу create-readme) наполняет его стандартизированным контентом.
• Может применяться к существующим репо без repo-init — тулза перезапишет README.md (локально) или обновит через GitHub API (с SHA).

8. Параметры тулзы (кратко)

create-readme:

• mode — "create" | "validate" (обязательный).
• repo_name, tagline, problem_en, solution_en, problem_ru, solution_ru, quick_start — обязательны для create.
• tier — "flagship" | "utility" (default utility).
• telegram — username без @ (optional).
• demo_gif — путь/URL (только для flagship).
• custom_sections_en / custom_sections_ru — массивы { title, content } (optional).
• repo — owner/name для удалённой операции (optional).
• file_path — локальный путь (default README.md).