# Skill0 Writer

> Соглашения по написанию документов skill0 — пирамидальная структура, ограничения на число строк, правила компоновки.

- Skill: `x-cmd/skill0-writer-16` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add x-cmd/skill0-writer-16`
- Raw SKILL.md: https://api.skillmd.com/api/skills/x-cmd/skill0-writer-16/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: x-cmd (https://skillmd.com/u/x-cmd)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/x-cmd/skill0-writer-16

---


# skill0-writer

Документы skill0 следуют **принципу пирамиды**: агенты могут прочитать только первые 10–30 строк, поэтому самая важная информация должна быть в начале. Детали после строки 30 — бонус, а не основная нагрузка.

## Что не ловят никакие правила

- **Ясность важнее краткости.** Короткий документ, дающий неправильный ответ, хуже длинного, дающего правильный.
- **Предупреждения о безопасности ДОЛЖНЫ быть явными** — используйте MUST, NEVER, DO NOT. Излагайте оговорки как полные утверждения, а не в скобках.
- **Не разворачивайте общеизвестное.** Если условного слова и пары предложений достаточно, остановитесь. Читатель уже знает, что такое YAML, git и кэш; тратьте контекст на то, что специфично для этого репозитория. Обычный виновник — обоснования: давайте причину правила только когда без неё оно кажется неверным. (`sw-1200`)
- **Таблицы — только для настоящих матриц.** 3+ столбцов, строки которых сопоставляются друг с другом. Двухколоночная таблица — список в обёртке таблицы — пишите список. Набор данных стоит выносить во внешний `.tsv` рядом с документом, со ссылкой, чтобы `x tsv` мог его запрашивать. (`sw-1250`)

## YFM — только `SKILL.md`

```yaml
---
name: <slug>                  # должен совпадать с именем каталога
description: <краткое описание в 1-2 предложения, по которому агент решает, загружать ли>
---
```

`name` и `description` несущественны. Всё остальное вкладывается в блок `metadata:` из [yfm](../yfm/SKILL.md) как скаляры через запятую — необязательно и добавляет структуру для индексации, обнаружения и онтологических хуков.

**Подфайлы не содержат YFM.** Loader фильтрует только `SKILL.md`, поэтому frontmatter нужен только ему. Любой другой файл (`references/*`, `usecase/*`, `EXAMPLE.md`, `*.report.md` …) читается напрямую агентом, который уже решил его открыть, — YFM там это чистые затраты токенов, повторяющие назначение, уже данное заголовком и первой строкой. Начинайте эти файлы с заголовка `#`. Отступление требует указанной в самом файле причины.

Для китайских локализаций используйте параллельный `SKILL.cn.md` (по одному на skill). Не смешивайте языки в одном файле.

## Механические проверки

Определены в [skill0-writer.rule.yml](skill0-writer.rule.yml). Запустите `x rule lint skill0-writer.rule.yml` и `x rule check -r skill0-writer.rule.yml lib/skill0/`. Покрытие: наличие YFM + полей name/description, формат name, число строк ≤ 100 (в идеале 50), порядок разделов install → usage → advanced → links, только английский, без вступления / без заключения / без повторов, без изолированных файлов.

## Проверка безопасности при усечении

После написания остановитесь на строке 30: не сформирует ли агент, остановившийся здесь, неправильного понимания?

Если да, переместите критическое уточнение выше. Первые 30 строк должны давать верную (пусть и неполную) ментальную модель. После строки 30 расширяйте деталями — пирамида самокорректируется.

## Двухслойная загрузка: description для сопоставления, body для справки

Загрузчики skills (Claude Code, Cursor, Continue и др.) загружают SKILL.md в два этапа:

  1. **YFM `description:`** — автоматически загружается в каталог агента
     для сопоставления. Агент читает description, чтобы решить,
     загружать ли skill.
  2. **Body** — загружается по запросу после сопоставления. Справочный материал.

Следствия:

- **Description** = *что это + когда загружать* — плотный по ключевым словам,
  богатый триггерами, сжатый.
- **Body** = *как использовать + справка* — примеры, схемы, граничные
  случаи, ссылки на более глубокие документы.

**Не дублируйте содержимое между двумя слоями.** Что бы description ни сообщал, body должен это *развивать*, а не повторять ту же поверхность. Первый абзац body особенно не должен перечислять те же особенности, что и description, — body начинается со справки, а не со второго резюме.

Практический тест: если полностью удалить description и прочитать только первые 30 строк body, агент всё равно должен видеть, что делает skill и когда его загружать. Если только description несёт эту информацию, body нечего добавить в начале — перенесите объяснение в body, а description оставьте с заголовком.

## Skill — это пакет знаний, а не учебник

Тело skill — **брифинг для LLM**, а не курс для новичка.

- **Способность** живёт в LLM. Body не учит.
- **Знание** живёт в инструментах данных x-cmd (`x wkp` / `x rfc` / `x cve`, NVD / MITRE / GHSA) и во внешних источниках. Body указывает; агент сам запрашивает.
- **Фрейминг** — работа skill: называет форму задачи, соглашение, структурированный вывод, используемый инструмент x-cmd.

Skill несёт угол решения, соглашение, форму вывода и указатели на источники. Он **не** несёт способности (она уже есть у LLM), статические данные (устаревают) или учебники (используйте sidecar'ы).

Когда детали слишком конкретны или слишком актуальны, выносите их в sidecar (`references/`, `ANALYTICS.md`) или во внешний всегда обновляемый документ.

## Внешние ссылки

Собирайте два типа: **root links** (точки входа вроде `llms.txt`, индекса документации) и **useful links** (точечные ссылки на 20% документации, покрывающие 80% случаев). Сначала root, затем useful — ИИ понимает порядок. **Без дублирования**, если только акцент не критичен.

## Мягкие оговорки (оценочные суждения)

- **Подфайлы (CLEANUP.md, references/*)** могут быть длиннее SKILL.md, но первые 20 строк всё равно несут нагрузку (та же пирамида).
- **ОБЯЗАН** ссылаться на каждый подфайл из родительского SKILL.md (прямая ссылка обязательна). Обратная ссылка из подфайла на родительский SKILL.md **необязательна** — файлы usecase неявно ссылаются на родителя через свой путь. Обеспечивается правилом `sw-1000-no-orphan-docs` в [skill0-writer.rule.yml](skill0-writer.rule.yml).
- **Спекуляции** — формулируйте проверенные факты, либо помечайте «untested».
- **Эмодзи** — если только тема skill этого не требует.

## Связанное

- [yfm](../yfm/SKILL.md) — соглашение YFM, чей первый уровень обеспечивает skill0-writer
- [naming](../naming/SKILL.md) — именование также следует правилам writer
- [skill0-writer.rule.yml](skill0-writer.rule.yml) — механическое обеспечение

