# Skill0 Writer

> Conventions for writing skill0 documents — pyramid structure, line limits, and layout rules.

- Skill: `x-cmd/skill0-writer-19` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add x-cmd/skill0-writer-19`
- Raw SKILL.md: https://api.skillmd.com/api/skills/x-cmd/skill0-writer-19/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-19

---


# 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>                  # must equal the directory name
description: <1-2 sentence summary an agent uses to decide whether to load>
---
```

`name` і `description` несуть основне навантаження. Усе інше вкладається в блок `metadata:` з [yfm](../yfm/SKILL.md) як скаляри, розділені комами — необов'язково, але це додає структуру для індексації, пошуку та онтологічних гачків.

**Підфайли не несуть YFM.** Лише `SKILL.md` фільтрує завантажувач, тому тільки він потребує фронтматтеру. Кожен інший файл (`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`, docs index) та **useful links** (точенкові посилання на ті 20% документів, які покривають 80% випадків використання). Спершу перелік root, потім useful — AI розуміє порядок. **Без дублювання**, якщо наголос не критичний.

## М'які застереження (судження)

- **Підфайли (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) — механічне забезпечення
