К основному содержанию
скилл CX Codex

technical-writing · riekelt — скилл для Claude Code: проверка техдокументов

Скилл technical-writing для Claude Code задаёт правила структуры, проверки фактов и стиля технических документов. Помогает писать README, спецификации, отчёты и планы.

MIT 27 800 установок ★ 40 обновлён 2026-09-13

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add riekelt/technical-writer --skill technical-writing -a claude-code
Открыть на GitHub

Что делает technical-writing

Скилл помогает писать, перестраивать и проверять технический текст: спецификации, дизайн-документы, README, справку, планы и отчёты. Он задаёт порядок работы с источниками, правила для правдивых утверждений и список нежелательных конструкций. Документы сохраняют язык исходного текста.

Перед черновиком скилл предлагает определить тип документа, аудиторию, цель и границы темы. Затем агент читает похожие документы, проверяет существующие материалы и выбирает правила для нормативного, описательного, исторического, процедурного или справочного текста. В наборе есть подсказки для подключения родственных скиллов, например для runbook или API-документации.

Скилл не управляет содержанием документа: факты нужно брать из источников проекта. Он также не предназначен для маркетинговых текстов и UI-микрокопирайтинга, хотя правила правдивости для них сохраняются.

Какие задачи решает

  • составить README по правилам репозитория
  • перестроить спецификацию перед публикацией
  • проверить технический текст на неподтверждённые утверждения
  • выбрать правила для runbook или API-документации

Примеры запросов агенту

  • Напиши README для этого репозитория и сначала определи его аудиторию, цель и границы.
  • Перепроверь этот дизайн-документ по правилам технического письма, не добавляя фактов из головы.
  • Приведи этот текст к правилам для справочной документации и проверь утверждения по исходникам.

Как установить technical-writing

1Через Skills CLI (Vercel)

npx skills add riekelt/technical-writer --skill technical-writing -a claude-code

2Вручную: положить файлы

~/.claude/skills/technical-writing/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/technical-writing/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о technical-writing

Как установить technical-writing в Claude Code?

Выполните npx skills add riekelt/technical-writer --skill technical-writing -a claude-code, затем проверьте файл ~/.claude/skills/technical-writing/SKILL.md.

Что делает technical-writing?

Скилл задаёт правила для технической прозы, работы с источниками и структуры документа. Он помогает агенту выбрать подход к README, спецификации, отчёту или справке.

Какие документы поддерживает technical-writing?

Он охватывает нормативные, описательные, исторические, процедурные и справочные документы, включая specs, design docs, README, runbook и API-документацию.

Исходный текст

SKILL.md · MIT
---
name: technical-writing
description: Use when writing, restructuring, or revising any technical document - specs, design docs, READMEs, reference documentation, plans, reports - or any prose that must survive being read twice by someone in a hurry. Encodes the house style, the truth and sourcing rules, and the banned-constructions list. Use whenever you produce repository-bound text longer than a paragraph, even if nobody says "document". Foundation for the sibling document-type skills.
---

# Technical writing

## Overview

House style for technical documents. The rules are in English; documents keep their own language: a Dutch document is written and reviewed in Dutch. The structural and truth rules apply in any language; the vocabulary lists in `references/style.md` are English-specific and other languages carry their own. Core principle: **a document states current, verified behavior, conclusion first, with every claim traceable to a source, and every fact living in exactly one place.** A thin document beats an overstated one.

These rules govern documents, not chat replies. Length and section rules apply to running prose, not to reference lists like this file.

## When to invoke

Load this skill for any technical prose, then the matching document-type skill on top. These are routing hints; each skill's own body is the authority.

When a repository regularly produces documents, record the invocation in project memory: one line in its CLAUDE.md or the platform's equivalent, telling agents to load this skill for any technical prose there.

| The task is | Also load |
|---|---|
| A proposal, RFC, design doc, spec, or migration plan | `writing-design-docs` |
| Recording a decision, an ADR, a decision log entry | `recording-decisions` |
| A changelog entry, release notes, "what shipped" | `writing-changelogs` |
| A runbook, setup guide, procedure, troubleshooting entry | `writing-runbooks` |
| A tracker item: epic, story, task, bug report, spike, acceptance criteria | `writing-issues` |
| A migration or deprecation guide | `writing-runbooks` |
| A postmortem, incident report, root-cause analysis | `writing-postmortems` |
| Documenting an existing, under-documented system; regrounding stale docs against code | `documenting-legacy-codebases` |
| A process, lifecycle, or interaction diagram; drawing business logic | `diagramming-processes` |
| An API reference: endpoints, message payloads, DTOs, CLI commands, file formats, webhooks | `documenting-contracts` |
| Reviewing or rewriting someone else's text; the final pass before delivering any document | `reviewing-technical-prose` |

## Non-goals

- Does not govern marketing copy, social posts, or UI microcopy; only the truth rules in `references/truth.md` still bind those.
- Does not decide content: what is true comes from the sources, not from the style.
- Does not license restyling existing documents that follow their own conventions; apply the precedence rules below.
- Does not yield to a request to make a document "punchy", "compelling", or "persuasive": the numbers persuade, the register stays plain.

## Mandatory checkpoint before drafting

Before drafting a new document or substantial section, derive and state in working notes:

`Kind: <normative|descriptive|historical|runbook|reference> | Audience: <who> | Purpose: <the verb the reader must accomplish> | Non-goals: <what this deliberately does not cover>`

Fill the fields from the request, sources, and repository context. State a safe assumption and continue when it does not materially change the result. Ask only when an unknown would change the audience, substance, or scope. Never invent a fact to complete the checkpoint; do not insert the checkpoint into the finished document unless its schema requires it.

## Read first, then write

Before writing a line:

1. Read up to two comparable documents in the same directory; adopt their structure, tone, and conventions. When fewer than two comparable documents exist, read every available example, then use repository-level conventions. Do not block because the directory is new.
2. Check for a `README.md` that indexes the documents. If it exists, add the new document to it.
3. Check whether the topic already lives somewhere. Extending the owner is almost always better than starting a rival document beside it.

## Rule precedence

When instructions conflict, apply them in this order:

1. Truth, safety, and historical-integrity rules.
2. An explicit exception in the active document-type skill.
3. The shared hard rules below.
4. An explicit schema and the conventions in the target directory.
5. Shared style preferences in `references/style.md`.

Existing practice controls only choices that a higher rule does not settle. It cannot weaken sourcing, rewrite accepted history, or represent unverified work as shipped. A document-type exception must name the rule it bends and the boundary of the exception.

An author's stated style choice outranks the shared style preferences, and nothing else. When the author says leave my voice alone, the style pass stops; truth, safety, and history stay binding whoever objects.

## Classify the document before editing it

The edit rule differs per kind. "Update docs to match code" is actively wrong for two of the five.

| Kind | Examples | Edit rule |
|---|---|---|
| Normative | architecture principles, contracts, style guides | If code violates the contract, do NOT water the contract down; record the violation. Edit only when the contract itself names deleted or renamed concepts. |
| Descriptive | flows, component docs, state machines | Update to match code exactly. Verify against implementations, not names. |
| Historical | changelogs, old specs, decision logs, applied migrations | Never rewrite history. Flag discrepancies; supersede with a new entry. |
| Runbook | operations, troubleshooting, release procedures | Update to match reality; every step must have been actually run. |
| Reference | API docs, config references, indexes | Exhaustive: every key, every flag, with defaults and a Usage column. |

If an entire document describes something deleted, do not delete the file: mark it obsolete with a one-line banner ("> NOTE: describes removed component X; see Y") and leave the removal to the owner.

## Hard rules

Non-negotiable, in every document:

- **No em dashes, no en dashes, no ` -- ` dashes.** Use commas, colons, semicolons, periods, parentheses, or ` - ` with spaces as an aside marker. A plain hyphen serves ranges (`2026-2030`). Check all three forms before delivery.
- **No changelog section and no "last updated" field inside a document.** This holds per sentence too: describe current behavior, never the previous behavior; "this step replaced the manual check" belongs in a migration doc or release note, not in a procedure.
- **No delivery history as narrative status in prose, comments, names, or strings**: no phases, task IDs, ticket keys, SHAs, or plan references that merely describe how work was delivered. A pinned commit may appear solely as claim evidence. Ticket keys may appear as functional metadata in tracker records, commit messages, planning documents, and citations; never in code comments or user-facing content.
- **Never state as fact what you cannot trace** to code at a cited path, a pinned commit, a test, a document, or a primary source. A plausible guess presented as fact is worse than "the source says nothing about this." See `references/truth.md`.
- **One fact, one home.** Everything else links to the owner. A summary may route, never decide: when an index and its source disagree, the source wins and the index is the bug.
- **Accepted decisions and applied migrations are immutable.** Corrections are new dated entries, never edits to history.
- **Headings in sentence case**, never Title Case.

## Workflow

1. **Read first** (above), and classify the document.
2. **Declare before drafting**: fill the checkpoint above (kind, audience, purpose, non-goals).
3. **Draft conclusion-first** at every level: document, chapter, paragraph. No run-up, no context paragraphs before the outcome. Each chapter opens with what came out of it, not how it was approached.
4. **Ground every claim** and label its confidence: `references/truth.md`.
5. **Style pass** over sentences, words, headings, and the banned-constructions list: `references/style.md`.
6. **Verify before delivery**: load `reviewing-technical-prose` for the checklist. Check references by actually following them.

## Audience

Know who you write for before starting. Not "users": the actual person, where they are, and the verb they must accomplish.

| Reader | What they need |
|---|---|
| Developers | The why behind the choice, and what changes about their work tomorrow |
| Tech leads / architects | Trade-offs, alternatives, long-term consequences |
| Management / product owner | What it yields, what it costs, which risks |
| External parties | No internal team names or jargon without explanation |

Several groups at once: the summary reads for the broadest group, the rest may deepen. A phrase that would need a footnote needs rewriting, not a footnote.

## Common mistakes

- Starting at the solution. First the problem, then the proposal.
- Documenting what the code already shows. Documents own reasoning, constraints, invariants, and alternatives; the code owns the what.
- Unverifiable claims: "faster", "better" without a number or source. Add the number or cut the claim.
- Filling a gap with a plausible guess instead of naming the gap.
- Vague owners: "this still needs investigation" without a name or role.
- Listing only benefits. Every proposal names its costs.
- Silently trimming, reordering for emphasis, or restyling a host document during an edit pass. Edits are surgical: preserve voice, structure, numbering, and IDs.
- A document past roughly 800 lines of prose: split it and let the main document link to the parts.

© riekelt · MIT · riekelt/technical-writer

Похожие скиллы

Все скиллы по теме «Тексты и документация» →

Сначала — technical-writing от других авторов.

technical-writing backnotprop Скилл technical-writing для Claude Code задаёт правила для документации, RFC, README и сообщений коммитов. Вызывается командой /technical-writing. CX Codex +1 10 700установок technical-writing frappe Скилл technical-writing заставляет агента писать прозу в стиле Simplified Technical English: короткие предложения, активный залог, одно слово — одно значение. Для документации, README и коммитов. CX Codex +1 766установок technical-writing Mindrally Скилл technical-writing задаёт правила для написания подробных руководств и документации для разработчиков. Помогает создавать технические статьи без клише и воды. CX Codex +1 1 200установок technical-writing proffesor-for-testing Скилл technical-writing задаёт правила технического текста: вести с пользы, подтверждать примерами и числами, резать лишние слова. Включается при написании постов, документации и туториалов. CX Codex +1 209установок technical-writing akillness technical-writing — скилл для Claude Code, который помогает писать техническую документацию для разработчиков и операторов. Выберите его для ADR, инструкций по эксплуатации или плана миграции. CX Codex +1 546установок technical-writer OneWave-AI Скилл technical-writer для Claude Code пишет и перестраивает техническую документацию по коду проекта. Включается для README, руководств, инструкций и объяснений кодовой базы. CX Codex +1 1 100установок technical-documentation wondelai Скилл technical-documentation для Claude Code, Codex, Cursor, GitHub Copilot и Gemini CLI, который проверяет, пишет и переписывает документацию по руководству Google Developer Documentation Style Guide. CX Codex +1 1 900установок documentation официальный anthropics Скилл documentation для Claude Code готовит README, справочники API, ранбуки, архитектурные документы и гайды для новичков. Включается, когда код уже есть, а описания нет. CX Codex +1 10 800установок diataxis pproenca Скилл diataxis раскладывает техническую документацию на четыре режима: туториал, инструкция, справочник, объяснение. Помогает решить, что писать на конкретной странице. CX Codex +1 149установок code-documentation-analyzer Jeremy Longshore Автоактивируемый скилл для разбора документации кода: API-справочники, руководства пользователя, архитектурные описания. Включается по фразам вроде «code documentation analyzer» или «code analyzer». CX Codex +1 1установок writing-documentation-with-diataxis sammcj Скилл writing-documentation-with-diataxis раскладывает техническую документацию на четыре типа по фреймворку Diataxis и помогает писать или проверять каждый из них. CX Codex +1 648установок

Из того же набора11

Весь набор →
reviewing-technical-prose Скилл reviewing-technical-prose для вычитки чужих технических текстов: находит запрещённые конструкции, слабые утверждения и структурные дефекты, а перед сдачей документа прогоняет чек-лист. CX Codex +1 26 900установок writing-design-docs Скилл writing-design-docs для Claude Code задаёт структуру RFC и архитектурных предложений: вывод, цели и не-цели, карточки Why & What и проверку на неопределённости. CX Codex +1 26 900установок writing-changelogs Скилл writing-changelogs готовит записи журнала изменений, релизные заметки и сводки о выпущенной работе. Нужен после заметных изменений, исправлений или удалений. CX Codex +1 26 700установок writing-runbooks Скилл writing-runbooks для написания ранбуков, инструкций по установке и миграции, где читатель выполняет шаги под давлением времени. CX Codex +1 26 700установок documenting-legacy-codebases Скилл documenting-legacy-codebases восстанавливает документацию по коду, когда старые доки устарели или врут. Сначала инвентаризация системы, потом текст. CX Codex +1 26 600установок writing-postmortems Скилл writing-postmortems для Claude Code помогает составить постмортем после сбоя, ошибки с последствиями для пользователей или инцидента, которого удалось избежать. Также превращает переписку и логи в документ с хронологией и задачами. CX Codex +1 26 600установок writing-issues Скилл writing-issues задаёт структуру задач, баг-репортов и спайков в трекере. Помогает превратить обсуждение или сырые заметки в понятный тикет с проверяемыми критериями приёмки. CX Codex +1 26 500установок recording-decisions Скилл recording-decisions записывает принятые решения в формате ADR или короткой записи журнала, пока они не остались только в чате. CX Codex +1 26 500установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой