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

---
name: repo-readme
description: 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` генерирует ровно эту структуру (параметры подставляются):

```markdown
# 🚀 {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`).