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`. Тулза гарантирует структуру (разделители, Features table,
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. 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 и поиска.

## 3. 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.

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

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

- `<!-- summary-en:start -->` ... `<!-- summary-en:end -->` — английский
  блок Why/What для карточки.
- `<!-- features-en:start -->` ... `<!-- features-en:end -->` — английская
  таблица фич.
- `<!-- summary-ru:start -->` ... `<!-- summary-ru:end -->` — русский блок
  Зачем/Что.
- `<!-- features-ru:start -->` ... `<!-- features-ru:end -->` — русская
  таблица фич.

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

## 5. Шаблон README (reference)

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

```markdown
# 🚀 {repo_name}
> {tagline}

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

---

## 🇬🇧 English

<!-- summary-en:start -->
### ❓ Why
{why_en}

### ✅ What
{what_en}
<!-- summary-en:end -->

<!-- features-en:start -->
### Features

| Feature | Description |
|---------|-------------|
| {emoji} {name} | {description} |
...
<!-- features-en:end -->
{custom_sections_en — доп. секции, если переданы}

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

---

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

<!-- summary-ru:start -->
### ❓ Зачем
{why_ru}

### ✅ Что
{what_ru}
<!-- summary-ru:end -->

<!-- features-ru:start -->
### Фичи

| Фича | Описание |
|------|----------|
| {emoji} {name} | {description} |
...
<!-- features-ru:end -->
{custom_sections_ru — доп. секции, если переданы}

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

---

## 💬 Support and contacts / Поддержка и контакты

Have questions or want to support?
👉 **[slaid098.dev/support](https://slaid098.dev/support)**
{telegram строка, если передан}
```

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

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

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

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

`create-readme`:

- `mode` — `"create"` | `"validate"` (обязательный).
- `repo_name`, `tagline`, `why_en`, `what_en`, `why_ru`, `what_ru`,
  `quick_start`, `features_en`, `features_ru` — обязательны для `create`.
- `features_en` / `features_ru` — массив `{ emoji, name, description }[]`.
- `custom_sections_en` / `custom_sections_ru` — массивы
  `{ title, content }` (optional).
- `telegram` — username без `@` (optional).
- `repo` — `owner/name` для удалённой операции (optional).
- `file_path` — локальный путь (default `README.md`).