General README Skill
Создание и обновление README на основе фактов с помощью AI-ассистентов для кода
v2.0.0 · Подтверждение настроек · Обновление по Git · Кроссплатформенность · Многоязычность
English · 中文 · 日本語 · 한국어 · Русский
## Быстрый старт
Этот репозиторий (каталог `general-readme-skill`) содержит два скилла: **`readme-write`** создаёт README, а **`readme-update`** поддерживает их актуальными по изменениям в Git. Основной процесс использует только штатные инструменты агента для чтения, поиска и редактирования. Необязательным офлайн-проверкам нужен **Python 3.9+**, сторонние пакеты не требуются.
### Установка readme-write
Скопируйте `SKILL.md`, `references/` и `scripts/` вместе в каталог скилла с именем `readme-write`. Сохраняйте относительные пути: если скопировать только `SKILL.md`, процесс будет неполным.
```bash
mkdir -p .claude/skills/readme-write
cp SKILL.md .claude/skills/readme-write/
cp -r references/ scripts/ .claude/skills/readme-write/
```
Для другого проекта укажите абсолютный путь к каталогу скиллов этого проекта и не перезаписывайте существующие инструкции команды. Руководства по интеграции: [Claude Code](../install/claude-code.md), [GitHub Copilot](../install/copilot.md), [Cursor](../install/cursor.md). Они описывают размещение файлов; фактическую загрузку нужно проверять в установленном хосте. Универсальный способ — вызов естественным языком; `/readme-write` и `/readme` — это триггерные фразы, а не гарантированные слэш-команды.
### Получение первого результата
Попросите агента хоста:
> Напиши README
Первый ответ собирает все неопределённые настройки в один вопрос и **останавливается до вашего ответа**. Ответьте своим выбором или «используй рекомендованные настройки». После подтверждения агент изучает статические данные проекта, записывает согласованные README и сообщает, какие проверки выполнены.
Чтобы явно передать выбор агенту:
> Сгенерируй README без вопросов. Английский, для разработчиков, сбалансированный макет, остальное реши сам.
Такое делегирование не разрешает удалять написанное вручную и не разрешает запускать команды установки или запуска проекта.
## Что меняет версия 2.0
| Проблема пользователя | Улучшение |
|---|---|
| Агент забывает спросить о настройках | Входной шлюз: без настоящего ответа или явного делегирования нет ни сканирования, ни генерации |
| Красивые, но нерабочие инструкции по установке | У команд, рабочих каталогов и первого примера должны быть подтверждения в проекте |
| Все README выглядят одинаково | Три макета — компактный, сбалансированный и витринный — и только уместные бейджи |
| Нет схемы или схема выдуманная | В каждом README есть блок-схема, основанная на исходном коде |
| Переводы расходятся | Все языковые версии одинаковы во всём, кроме языка |
| Обновления копятся в начале или конце | Каждое изменение ставится на естественное место |
| Обновление стирает текст мейнтейнера | Парные управляемые области; текст без маркеров считается написанным вручную |
Эти скиллы — инструкции, а не механизм принудительного исполнения. Шлюзы и оценочные сценарии снижают риск пропусков, но реальное соблюдение нужно проверять на агентах хоста.
## Настройки
Выбирайте каждый пункт отдельно, а не принимайте универсальный шаблон:
| Настройка | Варианты |
|---|---|
| Язык | Основной язык и только нужные переводы |
| Читатель | Пользователи, разработчики или участники проекта |
| Макет | Компактный, сбалансированный или витринный |
| Объём | Краткий, стандартный или подробный |
| Тон | Профессиональный, минималистичный или энергичный |
| Бейджи | Нет, flat, flat-square или for-the-badge |
| Изображения | Нет или уместные существующие материалы; блок-схема есть всегда |
| Обновления | По умолчанию сохранять; переписывать только в разрешённых пределах |
| Рендеринг | GitHub или переносимый Markdown |
| Эмодзи | Выключены, если их явно не запросили |
Предлагаемая отправная точка: язык запроса, пользователи, сбалансированный макет, стандартный объём, профессиональный тон, flat, существующие изображения, сохранение и GitHub. **Рекомендация — это не согласие.** Просьбу «сделай красиво» нельзя считать разрешением молча принять все значения по умолчанию. `--no-beautify` выбирает только компактный макет; `--yes`, «用默认值» или «你决定» делегируют неопределённые настройки.
## Дизайн для читателя
| Макет | Подходит для | Оформление |
|---|---|---|
| **Компактный** | Небольшие библиотеки и CLI | Markdown с выравниванием по левому краю, код пораньше, не более 2 бейджей |
| **Сбалансированный** | Большинство репозиториев | Понятный заголовок и следующий шаг, не более 4 бейджей, одно полезное изображение |
| **Витринный** | Продукты с реальной демонстрацией | Необязательный центрированный Hero, текстовые ссылки, один настоящий скриншот |
Тон не зависит от макета: профессиональный стиль не означает центрированный HTML, а энергичный — эмодзи. Настоящий скриншот помогает, выдуманный интерфейс — нет. Блок-схема есть в любом макете, а ассистент, написавший документ, не становится автоматически бейджем поддерживаемой платформы.
## Рабочий процесс
`readme-write` идёт по цепочке **Подтверждение → Изучение → План → Написание → Проверка → Передача**:
```mermaid
flowchart LR
A[Подтвердить настройки] --> B[Изучить данные проекта]
B --> C[Спланировать путь читателя]
C --> D[Написать содержимое и оформление]
D --> E[Проверить факты, ссылки и единообразие]
E --> F[Передать все языковые версии]
classDef step fill:#1e40af,stroke:#1e3a8a,color:#fff
class A,B,C,D,E,F step
```
1. **Подтверждение:** спросить один раз, дождаться ответа и кратко изложить принятые настройки.
2. **Изучение:** прочитать манифесты, точки входа, примеры, тесты и нужные настройки; никогда не запускать код проекта и не читать настоящие учётные данные.
3. **План:** выбрать путь к первому результату, блок-схему и только действительно полезные разделы.
4. **Написание:** писать содержимое и оформление на всех языках вместе, из одной канонической структуры.
5. **Проверка:** сверить подтверждения фактов, ссылки, якоря, маркеры, блок-схему и единообразие.
6. **Передача:** править только согласованные файлы и сообщать о фактически выполненных проверках.
Точка входа — [`SKILL.md`](../SKILL.md); подробные протоколы находятся в [`references/`](../references/).
## Скилл обновления
Вспомогательный скилл [`readme-update`](../side-skills/readme-update-skill/SKILL.md) (каталог исходников `side-skills/readme-update-skill`) обновляет существующие README по локальным изменениям в Git:
```mermaid
flowchart LR
U1[Спросить целевую версию] --> U2[Изучить слои изменений Git]
U2 --> U3[Сопоставить изменения с разделами]
U3 --> U4[Поставить каждый факт на естественное место]
U4 --> U5[Синхронизировать все языковые версии]
U5 --> U6[Обновить блок-схему и проверить]
classDef step fill:#047857,stroke:#065f46,color:#fff
class U1,U2,U3,U4,U5,U6 step
```
### Установка readme-update
Из корня этого репозитория, на примере установки Claude Code на уровне проекта:
```bash
mkdir -p .claude/skills/readme-update
cp side-skills/readme-update-skill/SKILL.md .claude/skills/readme-update/
cp -r side-skills/readme-update-skill/references side-skills/readme-update-skill/scripts .claude/skills/readme-update/
```
Попросите «обнови README» или «update README». Сначала агент спрашивает целевую версию проекта, явно предлагая вариант **оставить версию без изменений**, и ждёт ответа до начала правок; «你决定» этот вопрос не снимает, а уже названная вами версия повторно не запрашивается. Затем он локальными командами Git только для чтения изучает закоммиченные, подготовленные, неподготовленные и неотслеживаемые изменения и сопоставляет значимые для читателя изменения с затронутыми разделами.
Каждое изменение **вплетается в тот раздел, которому оно принадлежит**, рядом с ближайшим по смыслу элементом и в соответствии с порядком этого раздела. Ничего не дописывается в начало или конец только потому, что так проще, и журнал обновлений не добавляется. Область версии по умолчанию — только README: без правки манифестов, тегов, коммитов и релизов. Запасная точка отсчёта в Git — последнее изменение основного README, и она помечается как эвристика. Подробности: [протокол Git](../side-skills/readme-update-skill/references/git-delta.md), [правила версий](../side-skills/readme-update-skill/references/version-and-language-sync.md) и [правила размещения](../side-skills/readme-update-skill/references/placement-and-parity.md).
## Единообразие языков и блок-схемы
К каждому README, который пишет или обновляет любой из скиллов, применимы два правила:
1. **Блок-схема есть всегда.** В каждом README есть блок-схема реального основного потока, основанная на исходном коде. Если связи между компонентами подтвердить нельзя, рисуется проверенный процесс: установка, настройка, запуск и результат. Настройка «без изображений» убирает изображения, но не блок-схему.
2. **Все версии одинаковы.** В каждой языковой версии одни и те же разделы, таблицы, блоки кода, узлы и связи блок-схемы, ссылки, изображения и бейджи. Различается только язык; содержимое, существующее лишь в одной версии, не сохраняется.
Разошедшиеся версии приводятся к одной канонической структуре, а структура проверяется описанным ниже средством. Проверка единообразия доказывает лишь одинаковость структуры; точность перевода по-прежнему требует прочтения человеком.
## Безопасные обновления
При сопровождении через `readme-update` настоящее решение о версии разрешает только узкие, обоснованные правки в разделах без маркеров, но не переписывание. Явные ручные блоки и несвязанное содержимое остаются защищёнными. Для новых сгенерированных разделов используются стабильные парные маркеры:
```markdown
## Использование
Содержимое, специфичное для проекта.
```
Обновляйте только область между маркерами; сохраняйте текст вне её и явные блоки `MANUAL-START` / `MANUAL-END`. Существующие разделы без маркеров считаются написанными вручную, а устаревшие комментарии `AUTO-GENERATED` или `BEAUTIFIED` не дают права на полную перезапись. Подробности: [правила доказательств и обновлений](../references/evidence-and-updates.md).
## Контроль качества
Из корня этого репозитория проверьте целевой проект, не выполняя его код. Сначала укажите основной README, затем все переводы:
```bash
python3 scripts/check_readme.py --root /absolute/path/to/project --require-flowchart --parity /absolute/path/to/project/README.md /absolute/path/to/project/assets/README-zh.md
```
Добавьте `--json` для отчёта в машиночитаемом виде, а `--preferences /path/to/preferences.json` — только если пользователь разрешил сохранённую запись настроек. Проверка находит отсутствующие блок-схемы, расхождения структуры между языковыми версиями, отсутствующие локальные пути и якоря, пропущенный альтернативный текст изображений, незакрытые блоки кода, повреждённые маркеры, остатки шаблонов, форматы секретных значений с высокой достоверностью и отдельные ошибки Mermaid. Коды завершения: `0` — ошибок нет, `1` — ошибки проверки, `2` — сбой вызова или чтения.
Она **не доказывает** реальное согласие пользователя, фактическую точность, работоспособность примеров, доступность внешних ссылок, точность перевода, полную корректность Mermaid или отображение на GitHub. Подробности: [проверки качества и их ограничения](../references/quality-checks.md).
### Регрессионные тесты
```bash
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -v
```
Автоматические тесты охватывают средство проверки, инструмент разницы Git и контракты скиллов. В [`tests/behavior-cases.json`](../tests/behavior-cases.json) и [`side-skills/readme-update-skill/tests/behavior-cases.json`](../side-skills/readme-update-skill/tests/behavior-cases.json) собраны сценарии для оценки на реальных агентах хоста. Это спецификации оценки, а не утверждение, что все хосты их прошли.
## Направление развития
Приоритет: **надёжность настроек → достоверный первый опыт → безопасное сопровождение → одинаковые языковые версии**. Не делайте основной задачей следующей итерации таблицы бейджей или более крупные HTML-шаблоны. Далее нужно запустить поведенческие сценарии на реальных агентах хоста, а затем сравнить отрендеренные README типичных приложений, библиотек, CLI и монорепозиториев по [критериям оценки дизайна](../references/quality-checks.md#design-acceptance-rubric).
## Структура репозитория
| Путь | Назначение |
|---|---|
| `SKILL.md` | Точка входа `readme-write` и обязательный рабочий процесс |
| `references/` | Шлюз настроек, доказательства, разделы, дизайн, схемы, языки и проверки качества |
| `scripts/check_readme.py` | Офлайн-проверка только для чтения |
| `side-skills/readme-update-skill/` | Скилл `readme-update`, его справочные материалы и инструмент разницы Git |
| `tests/` | Автоматические проверки и поведенческие сценарии |
| `examples/` | Прежние иллюстративные результаты, а не проверенные эталоны |
| `install/` | Руководства по интеграции с хостами |
| `assets/` | Графика и переводы README |
## Участие в разработке
Меняя правила процесса, обновляйте соответствующий справочный материал и добавляйте поведенческий сценарий. Меняя средство проверки, добавляйте проходящие и непроходящие примеры и запускайте регрессионные тесты. Не помечайте сценарий как проверенный на хосте без записи реального запуска на хосте.
## Лицензия
[MIT](../LICENSE)