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 строка, если include_clone !== false}
{quick_start}
\`\`\`
{quick_start_steps_en — нумерованный список кликабельных шагов, если передан: 1. ... 2. ...}
{access_url строка если передан — Access at [url](url), кликабельна}
{development_en блок, если передан — ### 🔧 Development + content}

---

## 🇷🇺 Русский

<!-- 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 строка, если include_clone !== false}
{quick_start}
\`\`\`
{quick_start_steps_ru — нумерованный список кликабельных шагов, если передан: 1. ... 2. ...}
{access_url строка если передан — Доступ: [url](url), кликабельна}
{development_ru блок, если передан — ### 🔧 Разработка + content}

---

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

👉 **[slaid098.dev/support](https://slaid098.dev/support)**
```

`validate` проверяет: наличие всех 4 пар EN/RU разделителей (summary +
features), непустой контент между ними, ссылку `slaid098.dev/support`, секции
Quick Start (EN) и Быстрый старт (RU), language switcher `[English]` /
`[Русский]`, заголовок `## 🇷🇺 Русский` (не "Русская версия"), anchor
`[Русский](#-русский)` (не `#-русская-версия`). Шаги `quick_start_steps_*`
не влияют на валидацию — они рендерятся вне delimiter-пар (summary/features).

## 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).
- `access_url` — URL для Access/Доступ строки после Quick Start bash-блока
  (optional). EN: `Access at {url}`, RU: `Доступ: {url}`. Omit if no web access.
  Рендерится как markdown-ссылка `[url](url)` — кликабельна на GitHub.
- `include_clone` — boolean (optional, default true). `false` убирает `git clone`
  из Quick Start. Для userscript, web-app, npm-package.
- `quick_start_steps_en` / `quick_start_steps_ru` — массивы raw-markdown строк
  (optional). Каждая строка = один шаг, может содержать markdown-ссылки
  `[text](url)`. Рендерятся как нумерованный список `1. ... 2. ...` ПОСЛЕ
  bash-блока, ДО `access_url`. Кликабельные шаги для setup, где установка — это
  не одна команда, а несколько ссылок (установить userscript, получить API-ключ,
  настроить). Если массив пуст/не передан — шаги не рендерятся (backward compat).
- `development_en` — raw markdown (optional). `### 🔧 Development` после EN
  Quick Start, вне delimiter-тегов (не на slaid098.dev).
- `development_ru` — raw markdown (optional). `### 🔧 Разработка` после RU
  Быстрый старт, вне delimiter-тегов (не на slaid098.dev).
- `repo` — `owner/name` для удалённой операции (optional).
- `file_path` — локальный путь (default `README.md`).

## 8. Кейс: userscript / web-app / npm-package

Для репо без клонирования (userscript, web-app с demo URL, npm-package):

- `include_clone: false` — убирает `git clone` из Quick Start
- `quick_start` — команда установки (npm install, pip install, или ссылка на
  установку userscript). Если установка — это несколько ссылок (а не одна
  команда), лучше использовать `quick_start_steps_*` вместо/вместе с bash-блоком.
- `quick_start_steps_en` / `quick_start_steps_ru` — кликабельные шаги setup
  (рекомендуется для userscript/multi-step setup): установить userscript,
  получить API-ключ, настроить. Каждая строка может содержать `[text](url)`.
  Рендерятся как нумерованный список ПОСЛЕ bash-блока.
- `access_url` — URL web-доступа (если есть), рендерится как `[url](url)`.
- `development_en` / `development_ru` — инструкции для разработчиков (как
  собрать, как контрибьютить), рендерятся после Quick Start, вне
  delimiter-тегов (не на slaid098.dev)

### Пример: userscript со шагами-ссылками

```json
{
  "mode": "create",
  "repo_name": "my-userscript",
  "tagline": "One-line tagline.",
  "why_en": "Why this exists.",
  "what_en": "What it does.",
  "why_ru": "Зачем этот проект.",
  "what_ru": "Что делает.",
  "quick_start": "",
  "include_clone": false,
  "features_en": [{ "emoji": "⚡", "name": "Fast", "description": "Instant setup" }],
  "features_ru": [{ "emoji": "⚡", "name": "Быстрый", "description": "Мгновенный старт" }],
  "access_url": "http://localhost:4096",
  "quick_start_steps_en": [
    "Install the [userscript](https://greasyfork.org/...)",
    "Get a [Groq API key](https://console.groq.com/keys)",
    "Configure [settings](https://example.com/settings)"
  ],
  "quick_start_steps_ru": [
    "Установи [юзерскрипт](https://greasyfork.org/...)",
    "Получи [ключ Groq](https://console.groq.com/keys)",
    "Настрой [параметры](https://example.com/settings)"
  ]
}
```

Результат (EN секция):

```markdown
### ⚡ Quick Start
1. Install the [userscript](https://greasyfork.org/...)
2. Get a [Groq API key](https://console.groq.com/keys)
3. Configure [settings](https://example.com/settings)

Access at [http://localhost:4096](http://localhost:4096)
```

`include_clone: false` + `quick_start: ""` → bash-блок не рендерится (только
шаги). Если `quick_start` непустой — bash-блок рендерится перед шагами.