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. Тулза гарантирует структуру (разделители, 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 генерирует ровно эту структуру (параметры подставляются):

# 🚀 {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}
\`\`\`
{access_url строка если передан — Access at {url}}

---

## 🇷🇺 Русский

<!-- 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}
\`\`\`
{access_url строка если передан — Доступ: {url}}

---

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

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

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

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).
• access_url — URL для Access/Доступ строки после Quick Start bash-блока (optional). EN: Access at {url}, RU: Доступ: {url}. Omit if no web access.
• repo — owner/name для удалённой операции (optional).
• file_path — локальный путь (default README.md).