slaid098/opencode-config
1
0
Fork 0
Code Issues 3 Pull requests Projects Releases Packages Wiki Activity Actions
opencode-config/.opencode/skills/repo-readme/SKILL.md
Sergey b3aac737eb
feat(spec): project template skill init and check flow (#237) 
* feat(spec): add project-template skill init and check flow

* refactor(spec): remove repo-init migrate references to project-template

* test(spec): structural tests for project-template skill and command

* fix(test): wrap long lines and use non_templated var in project template tests

* fix(ci): reformat test_project_template_skill.py for ruff format

---------

Co-authored-by: opencode-agent <agent@opencode.local>
2026-08-03 17:37:55 +03:00

17 KiB
Raw Blame History

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 с гарантированной структурой (включая ![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. create-readme (mode: validate) → проверяет, что структура не нарушена (теперь в т.ч. наличие assets/cover.png reference).
  5. Если validate fails → фикс нарушения → re-validate. Цикл пока не пройдёт.

Локальный режим (по умолчанию): тулза пишет в 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/<name>.svg), либо имя brand-logo (резолвится из brand-logos/<name>.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-en:start --> ... <!-- tagline-en:end --> — английский tagline (короткая фраза для карточки).
  • <!-- tagline-ru:start --> ... <!-- tagline-ru:end --> — русский tagline.
  • <!-- 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}

![Cover](assets/cover.png)

<!-- tagline-en:start -->
> {tagline_en}
<!-- tagline-en:end -->
<!-- tagline-ru:start -->
> {tagline_ru}
<!-- tagline-ru:end -->

[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 проверяет: наличие всех 6 пар EN/RU разделителей (tagline + summary + features), непустой контент между ними, H1 title prefix # 🚀 , cover image reference assets/cover.png (substring-чек, без проверки существования файла), ссылку slaid098.dev/support, секции Quick Start (EN) и Быстрый старт (RU), language switcher [English] / [Русский], заголовок ## 🇷🇺 Русский (не "Русская версия"), anchor [Русский](#-русский) (не #-русская-версия). Флагирует ручной заголовок ## License / ## LICENSE / ## Лицензия как ERROR — дубликат 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" | "validate" (обязательный).
  • 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 со шагами-ссылками

{
  "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 секция):

### ⚡ 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-en:start/end --> и <!-- tagline-ru:start/end -->.

Миграция: замени "tagline": "..." на "tagline_en": "..." + "tagline_ru": "...". Старые вызовы с tagline падают с ❌ tagline_en is required for create mode.

Существующие README (без tagline delimiter-тегов) станут invalid при validate — Missing <!-- tagline-en:start --> delimiter и Missing <!-- tagline-ru:start --> delimiter. Регенерация README через create (с новыми параметрами) делается отдельным шагом после merge.