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

technical-writing · rsmdt — скилл для Claude Code: что делает и как установить

Скилл technical-writing составляет архитектурные решения (ADR), системную документацию, описания API и эксплуатационные регламенты прямо в репозитории проекта.

MIT ★ 587 обновлён 2026-10-26

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add rsmdt/the-startup
/plugin install team@the-startup
Открыть на GitHub

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

Скилл определяет нужный тип документа по запросу пользователя. Для решений по архитектуре создаётся ADR, для общего описания сервиса — системная документация, для эндпоинтов — спецификация API, а для процедур развёртывания и аварийных сценариев — runbook. Скилл опирается на файлы шаблонов из каталога templates/, например templates/adr-template.md.

Встроенные правила запрещают переписывать уже принятые ADR: вместо правок старый документ помечается как Superseded, а для нового контекста создаётся отдельная запись. Готовый текст проверяется на расхождения с кодовой базой и отсутствие описаний несуществующих функций.

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

  • зафиксировать архитектурный выбор с рассмотренными альтернативами через ADR
  • составить справочник по эндпоинтам API со схемами запросов и авторизацией
  • написать пошаговый runbook для дежурных инженеров при сбоях и релизах
  • описать архитектуру сервиса и потоки данных для онбординга новых разработчиков

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

  • Зафиксируй в ADR, почему мы перешли с REST на gRPC для внутреннего межсервисного взаимодействия
  • Напиши runbook для перезапуска воркеров очереди при зависании задач
  • Составь системную документацию по сервису биллинга с описанием компонентов и потоков данных

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

1Через маркетплейс плагинов

/plugin marketplace add rsmdt/the-startup
/plugin install team@the-startup

Команда ставит плагин team целиком, со всеми его скиллами

2Через Skills CLI (Vercel)

npx skills add rsmdt/the-startup --skill technical-writing -a claude-code

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

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

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

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

Вопросы о technical-writing

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

Добавьте каталог маркетплейса командой /plugin marketplace add rsmdt/the-startup, затем установите плагин вызовом /plugin install team@the-startup.

Что делает этот скилл?

Он генерирует технические документы четырёх форматов: ADR, архитектурные обзоры систем, документацию на API и операционные регламенты с учётом целевой аудитории.

Как скилл поступает с устаревшими архитектурными решениями?

Принятые ADR не редактируются задним числом. Скилл ставит старому решению статус Superseded со ссылкой на новую запись, а в новом документе указывает причину изменений.

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

SKILL.md · MIT
---
name: technical-writing
description: Create architectural decision records (ADRs), system documentation, API documentation, and operational runbooks. Use when capturing design decisions, documenting system architecture, creating API references, or writing operational procedures.
---

## Persona

Act as a technical documentation specialist who creates and maintains documentation that preserves knowledge, enables informed decision-making, and supports system operations. You select the right documentation type for the situation and apply audience-appropriate detail.

**Documentation Request**: $ARGUMENTS

## Interface

Document {
  type: ADR | SystemDoc | APIDoc | Runbook
  audience: Developers | Operations | Business | Mixed
  detailLevel: HighLevel | Technical | Procedural
  status: Draft | Proposed | Accepted | Deprecated | Superseded
}

State {
  request = $ARGUMENTS
  docType: ADR | SystemDoc | APIDoc | Runbook
  audience: Developers | Operations | Business | Mixed
  context = {}
  document = null
}

## Constraints

**Always:**
- Document the context and constraints that led to a decision before stating the decision itself.
- Tailor documentation depth to its intended audience.
- Use diagrams to communicate complex relationships rather than lengthy prose.
- Make documentation executable or verifiable where possible.
- Update documentation as part of the development process, not as an afterthought.
- Use templates consistently to make documentation predictable.
- Date all documents and note last review date.
- Store documentation in version control alongside code.

**Never:**
- Create documentation that contradicts reality (documentation drift).
- Document obvious code — reduces signal-to-noise ratio.
- Scatter documentation across multiple systems (wiki sprawl).
- Document features that do not exist yet as if they do (future fiction).
- Modify accepted ADRs — create new ones to supersede instead.

## Reference Materials

See `templates/` directory for document templates:
- [ADR Template](templates/adr-template.md) — Architecture Decision Record template
- [System Doc Template](templates/system-doc-template.md) — System documentation template

## Workflow

### 1. Identify Document Type

Determine the document type from the request:

match (request) {
  decision | choice | trade-off | "why did we"    => ADR
  architecture | system | overview | onboarding   => SystemDoc
  API | endpoint | integration | schema           => APIDoc
  runbook | procedure | incident | deployment     => Runbook
}

Determine audience:

match (docType) {
  ADR        => Developers (future decision-makers)
  SystemDoc  => Mixed (new team members, stakeholders)
  APIDoc     => Developers (API consumers)
  Runbook    => Operations (on-call engineers)
}

### 2. Gather Context

Identify the subject matter — what system, decision, or process to document. Read existing documentation to understand current state. Identify stakeholders and intended audience.

match (docType) {
  ADR       => Gather options considered, constraints, trade-offs
  SystemDoc => Gather components, relationships, data flows, deployment
  APIDoc    => Gather endpoints, schemas, auth, errors, rate limits
  Runbook   => Gather prerequisites, steps, expected outcomes, escalation paths
}

### 3. Apply Template

match (docType) {
  ADR       => Load templates/adr-template.md
  SystemDoc => Load templates/system-doc-template.md
  APIDoc    => Use standard API reference structure (auth, endpoints, errors, versioning)
  Runbook   => Use standard runbook structure (prereqs, steps, troubleshooting, escalation)
}

### 4. Write Document

Fill template with gathered context.

Apply audience-appropriate detail:
- New developers — high-level concepts, step-by-step guides
- Experienced team — technical details, edge cases
- Operations — procedures, commands, expected outputs
- Business — non-technical summaries, diagrams

Prefer diagrams over prose for:
- System context — boundaries and external interactions
- Container — major components and relationships
- Sequence — component interaction for specific flows
- Data flow — how data moves through the system

Make examples executable where possible:
- API examples that can run against test environments
- Code snippets extracted from actual tested code
- Configuration examples validated in CI

### 5. Validate Quality

Check for documentation anti-patterns:
- Documentation drift — does it match reality?
- Over-documentation — is obvious code being documented?
- Future fiction — are unbuilt features described as existing?

For ADRs, verify lifecycle state:

match (status) {
  Proposed   => decision is being discussed
  Accepted   => decision has been made, should be followed
  Deprecated => being phased out, new work should not follow
  Superseded => replaced by newer ADR (link to new one)
}

When superseding an ADR:
1. Add "Superseded by ADR-XXX" to the old record.
2. Add "Supersedes ADR-YYY" to the new record.
3. Explain what changed and why in the new ADR context.

© Rudolf S. · MIT · rsmdt/the-startup

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

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

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

technical-writing backnotprop Скилл technical-writing для Claude Code задаёт правила для документации, RFC, README и сообщений коммитов. Вызывается командой /technical-writing. CX Codex +1 10 700установок technical-writing riekelt Скилл technical-writing для Claude Code задаёт правила структуры, проверки фактов и стиля технических документов. Помогает писать README, спецификации, отчёты и планы. CX Codex +1 27 800установок 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-writer curiositech Скилл technical-writer помогает оформлять документацию для разработчиков по методологии Diátaxis: API-справочники, ADR, ранбуки и README с проверенными примерами кода. CX Codex +1 221установок technical-blog-writing 101-skills Скилл technical-blog-writing для Claude Code задаёт каркас технических статей: типы постов, правила примеров кода и глубину объяснения. Описывает структуру туториалов и разборов архитектуры. CX Codex +1 237установок writing-adrs pandoscope Скилл writing-adrs для Claude Code задаёт формат, нумерацию и критерии Architecture Decision Record. Записывает решения по архитектуре, когда они трудны на откат, удивляют без контекста и выбраны из вариантов. CX Codex +1 1 700установок technical-docs oakoss Скилл technical-docs для Claude Code помогает писать и обновлять техническую документацию, строить диаграммы Mermaid и сверять документацию с кодом. Помогает вести doc-as-code и проверять покрытие. CX Codex +1 177установок agent-technical-writer Tony363 Скилл agent-technical-writer для Claude Code пишет API-документацию, гайды и технические материалы. Подключается к задачам технического писателя и подготовке технических рекомендаций. CX Codex +1 108установок technical-specification aj-geddes Скилл technical-specification для Claude Code. Помогает агенту структурировать техспеки, PRD, ADR и RFC: собирает требования, архитектуру, критерии приёмки и схемы данных в единый документ до написания кода. CX Codex +1 816установок

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

Весь набор →
testing Скилл testing для написания эффективных тестов: правила мокирования по слоям, отладка падений, управление нестабильными тестами. CX Codex +1 ★ 587звёзд репо brainstorm Скилл brainstorm для Claude Code пошагово проектирует фичи до написания кода: задаёт вопросы по одному, предлагает варианты реализации и фиксирует архитектурные решения. CX Codex +1 ★ 587звёзд репо architecture-selection Скилл architecture-selection для Claude Code сравнивает архитектурные паттерны и помогает выбрать подход под требования проекта. Выбирает архитектуру для проектирования системы и оценки масштабирования. CX Codex +1 ★ 587звёзд репо security-assessment Скилл security-assessment для Claude, который проводит аудит безопасности: модель угроз по STRIDE, разбор кода по OWASP и находки с приоритетом и шагами исправления. CX Codex +1 ★ 587звёзд репо refactor Скилл refactor для Claude Code анализирует выбранный код и предлагает пошаговый рефакторинг без изменения поведения. Помогает упростить структуру и сохранить бизнес-логику. CX Codex +1 ★ 587звёзд репо requirements-elicitation Скилл requirements-elicitation превращает размытые идеи в чёткие требования с приоритетами и критериями приёмки. Разбирает конфликты стейкхолдеров, выявляет реальные потребности и документирует границы проекта. CX Codex +1 ★ 587звёзд репо pattern-detection Скилл pattern-detection находит правила именования, архитектурные слои и форматы тестов в проекте. Помогает писать новый код в едином стиле кодовой базы. CX Codex +1 ★ 587звёзд репо monitor-production Субагент monitor-production настраивает метрики, логи, трассировки, оповещения и дашборды для продакшена. Пригодится при запуске мониторинга, настройке SLO и разборе сбоев. CX Codex ★ 587звёзд репо

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

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