--- 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** → `.opencode/scripts/project-status.py` (`check_readme`) — проверяет, что структура соответствует стандарту витрины. - **После ручных правок README** → всегда проверка через `check_readme`. Любая правка руками агента (через 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 с гарантированной структурой (включая `![Cover](assets/cover.png)` после H1). 2. `draw-image` (template `"cover"`, slots по типу репо, `title`, `subtitle`, `out: "./assets/cover.png"`) → рендерит cover-изображение (1024×1024 PNG) на место, на которое ссылается README. Default `out` у `draw-image` уже `"./assets/cover.png"` — можно не передавать. 3. Ручные правки если нужно (агент редактирует файл напрямую через Edit) — например, расширить `custom_sections`, поправить формулировки. 4. Проверка через `.opencode/scripts/project-status.py` (`check_readme`) → структура соответствует стандарту витрины (в т.ч. наличие `assets/cover.png` reference). 5. Если проверка fails → фикс нарушения → повторная проверка. Цикл пока не пройдёт. Локальный режим (по умолчанию): тулза пишет в `file_path` (default `README.md`) через `fs.writeFileSync`, путь резолвится относительно рабочей директории сессии (`context.worktree`) — существующий файл перезаписывается. Удалённый режим: передай `repo` (`owner/name`) — тулза сделает PUT через `gh api repos/{owner}/{repo}/contents/README.md` с base64-контентом и SHA. ### Slot-выбор для cover `draw-image` template `cover` имеет 3 опциональных слота. Значение slot — либо имя Lucide-иконки (резолвится из `icons/lucide/.svg`), либо имя brand-logo (резолвится из `brand-logos/.svg`), либо путь к файлу (`./...` / `/...` / `../...`). - `icon` — основная иконка (400×400, slot recolor=accent). Для репо, ассоциированных с продуктом/брендом — brand-logo (напр. `opencode`). Для утилит/SDK/скриптов — Lucide (напр. `square-terminal`, `code-xml`, `brain-circuit`). - `sub-icon` — опциональная вторая иконка (200×200, recolor=accent). Lucide (напр. `git-branch`, `bot`, `terminal`). - `badge` — опциональная третья иконка (180×180, bg=surface, border=accent, radius=0.5). Lucide или путь к файлу (напр. логотип-плашка). Cover сохраняется в `assets/cover.png` (default `draw-image` out path). README ссылается именно на этот путь через `![Cover](assets/cover.png)`. ## 4. Зачем разделители (контекст для агента) Витрина **slaid098.dev** скачивает raw `README.md` из каждого репо и извлекает фрагменты между разделителями: - `` ... `` — английский tagline (короткая фраза для карточки). - `` ... `` — русский tagline. - `` ... `` — английский блок Why/What для карточки. - `` ... `` — английская таблица фич. - `` ... `` — русский блок Зачем/Что. - `` ... `` — русская таблица фич. Поэтому структура README **должна быть гарантирована тулзой**, а не агентом. Агент может менять текст *внутри* разделителей, но не должен удалять/двигать сами разделители. `check_readme` ловит такие нарушения. ## 5. Шаблон README (reference) Тулза `create-readme` генерирует ровно эту структуру (параметры подставляются): ```markdown # 🚀 {repo_name} ![Cover](assets/cover.png) > {tagline_en} > {tagline_ru} [English](#-english) | [Русский](#-русский) --- ## 🇺🇸 English ### ❓ Why {why_en} ### ✅ What {what_en} ### Features | Feature | Description | |---------|-------------| | {emoji} {name} | {description} | ... {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} --- ## 🇷🇺 Русский ### ❓ Зачем {why_ru} ### ✅ Что {what_ru} ### Фичи | Фича | Описание | |------|----------| | {emoji} {name} | {description} | ... {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/contacts](https://slaid098.dev/contacts)** ``` `check_readme` (project-status.py) проверяет: наличие всех 6 пар EN/RU разделителей (tagline + summary + features), непустой контент между ними, H1 title prefix `# 🚀 `, **cover image reference `assets/cover.png`** (substring-чек, без проверки существования файла), ссылку `slaid098.dev/contacts`, секции Quick Start (EN) и Быстрый старт (RU), language switcher `[English]` / `[Русский]`, заголовок `## 🇷🇺 Русский` (не "Русская версия"), anchor `[Русский](#-русский)` (не `#-русская-версия`). Флагирует ручной заголовок `## License` / `## LICENSE` / `## Лицензия` как FAIL — дубликат GitHub sidebar (GitHub рендерит license из LICENSE-файла). Шаги `quick_start_steps_*` не влияют на валидацию — они рендерятся вне delimiter-пар (summary/features). ## 6. Независимость от project-template - Скилл `project-template` (init flow) создаёт проект через cookiecutter — шаблон уже включает `README.md` с базовой структурой. - `repo-readme` (через тулзу `create-readme`) **наполняет** его стандартизированным контентом (delimiter tags, bilingual, cover). - Может применяться к существующим репо без `project-template` — тулза перезапишет `README.md` (локально) или обновит через GitHub API (с SHA). ## 7. Параметры тулзы (кратко) `create-readme`: - `mode` — `"create"` (обязательный). - `repo_name`, `tagline_en`, `tagline_ru`, `why_en`, `what_en`, `why_ru`, `what_ru`, `quick_start`, `features_en`, `features_ru` — обязательны для `create`. - `repo_name` — должен быть **lowercase kebab-case** (regex `^[a-z0-9]+(-[a-z0-9]+)*$`): только `a-z`, `0-9`, одиночные дефисы. Uppercase, underscores, пробелы, leading/trailing/consecutive dashes — отвергаются. - `tagline_en` — короткий английский tagline (1 предложение). **Не должен содержать кириллицы** (валидируется regex `/[ЁА-яё]/`). - `tagline_ru` — короткий русский tagline (1 предложение). **Должен содержать кириллицу** (валидируется regex `/[ЁА-яё]/`). Гарантирует, что русский tagline реально на русском, а не копия английского. - `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_en": "One-line tagline.", "tagline_ru": "Короткий теглайн.", "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-блок рендерится перед шагами. ## 9. Breaking change: tagline → tagline_en + tagline_ru Параметр `tagline` **удалён** (PR #150). Раньше был один английский tagline; теперь два — `tagline_en` (EN) и `tagline_ru` (RU) — оба обязательны для `create`. Витрина slaid098.dev парсит оба через delimiter-теги `` и ``. **Миграция:** замени `"tagline": "..."` на `"tagline_en": "..."` + `"tagline_ru": "..."`. Старые вызовы с `tagline` падают с `❌ tagline_en is required for create mode`. **Существующие README** (без tagline delimiter-тегов) станут invalid при проверке `check_readme` — `Missing delimiter` и `Missing delimiter`. Регенерация README через `create` (с новыми параметрами) делается отдельным шагом после merge.