ca2a04ce47
* refactor(templates): remove README.md from cookiecutter templates * test(templates): drop README expectations, expect WARN instead * docs(skills): note README is generated post-init via repo-readme * docs(skills): repo-readme creates README from scratch post-init * fix(templates): drop readme field from pyproject after README removal --------- Co-authored-by: opencode-agent <agent@opencode.local>
323 lines
17 KiB
Markdown
323 lines
17 KiB
Markdown
---
|
||
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 с гарантированной
|
||
структурой (включая `` после 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/<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 ссылается именно на этот путь через ``.
|
||
|
||
## 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 **должна быть гарантирована тулзой**, а не агентом.
|
||
Агент может менять текст *внутри* разделителей, но не должен удалять/двигать
|
||
сами разделители. `check_readme` ловит такие нарушения.
|
||
|
||
## 5. Шаблон README (reference)
|
||
|
||
Тулза `create-readme` генерирует ровно эту структуру (параметры подставляются):
|
||
|
||
```markdown
|
||
# 🚀 {repo_name}
|
||
|
||
|
||
|
||
<!-- 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/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 НЕ содержат (issue #269): свежий проект рождается без
|
||
README.
|
||
- `repo-readme` (через тулзу `create-readme`) **создаёт** полный README с нуля
|
||
(delimiter tags, bilingual, cover) по ручному вызову после init.
|
||
- Может применяться к существующим репо без `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-en:start/end -->` и `<!-- tagline-ru:start/end -->`.
|
||
|
||
**Миграция:** замени `"tagline": "..."` на `"tagline_en": "..."` +
|
||
`"tagline_ru": "..."`. Старые вызовы с `tagline` падают с
|
||
`❌ tagline_en is required for create mode`.
|
||
|
||
**Существующие README** (без tagline delimiter-тегов) станут invalid при
|
||
проверке `check_readme` — `Missing <!-- tagline-en:start --> delimiter` и
|
||
`Missing <!-- tagline-ru:start --> delimiter`. Регенерация README через
|
||
`create` (с новыми параметрами) делается отдельным шагом после merge.
|