docs-writer

Навык docs-writer помогает Gemini CLI писать, проверять и редактировать файлы Markdown и документацию в репозитории. Его нужно применять, когда задача касается каталога /docs или любого файла с расширением .md. Главная цель — получить документацию, которая точно отражает текущий код, имеет ясную структуру и сохраняет единый профессиональный тон. Исходный SKILL.md описывает роль технического автора и редактора для Gemini CLI: сначала нужно понять запрос и реализацию, затем подготовить текст, проверить ссылки и самостоятельно перечитать результат. Навык не заменяет исследование проекта: его центральное требование — не приписывать документации поведение, которого нет в коде и актуальных файлах. Рекомендованный голос обращается к читателю напрямую, использует активный залог и настоящее время. Формулировки должны быть профессиональными, дружелюбными и прямыми, с простой лексикой без маркетинговой гиперболы и лишнего жаргона. Требования нужно отличать от рекомендаций: для обязательного условия используется must, а расплывчатое should источник просит избегать. Для международной аудитории предпочтителен стандартный американский английский без идиом и культурных ссылок. В тексте следует писать precise технические глаголы, избегать please и антропоморфизмов, а аббревиатуры раскрывать обычными словами вместо латинских сокращений. При описании quota и limit важно не смешивать административную квоту и числовой предел. Форматирование строится вокруг понятного пути пользователя. После каждого heading нужен вводный абзац, а не сразу список или подзаголовок; перенос строк обычно ограничивается 80 символами. Заголовки и выделенные названия используют sentence case. Последовательные действия оформляются нумерованным списком, остальные элементы — маркированным; каждый шаг начинается с повелительного глагола и сначала сообщает условие, если оно важно. Названия файлов, команды, snippets и API оформляются code font, элементы интерфейса — bold. Для доступности нужны семантические HTML-элементы и осмысленный alt-текст для изображений. Дополнительные или объёмные сведения можно поместить в details. Markdown alerts разрешены для NOTE, TIP, IMPORTANT, WARNING и CAUTION, но перед блоком требуется prettier-ignore комментарий, чтобы форматтер сохранил разметку. Ссылки должны быть понятны вне контекста: не используйте click here. Внутри /docs применяйте относительные ссылки без добавления сегмента /docs/ и проверяйте, что результирующий путь существует. При изменении заголовка нужно найти deep links и обновить их. В структуре документации навык рекомендует начинать с BLUF — короткого объяснения того, что читатель получит. Для экспериментальной возможности предупреждение NOTE ставится сразу после вводного абзаца. Процедура должна вести пользователя от контекста к действию, опциональные шаги нужно помечать явно, а в конце при наличии дальнейшего пути добавляется раздел Next steps. Оглавление не является обязательной частью и при наличии его рекомендуют убрать. Перед редактированием docs-writer требует пройти подготовку. Сначала нужно уточнить, это новая документация или правка существующей, и снять неоднозначность запроса. Затем исследовать релевантный код, прежде всего в packages/, прочитать актуальные файлы docs/, найти страницы и файлы, которые ссылаются на изменяемый материал, и проверить, нужен ли sidebar.json. После этого формулируется план. Для отдельного аудита docset источник предусматривает процедурный docs-auditing.md. Такой порядок нужен, чтобы не исправить только текст, оставив устаревший пример, навигацию или ссылку на старый heading. На этапе исполнения результат должен отражать найденную реализацию и существующие правила проекта. При редактировании проверьте неполные места, структуру BLUF и последовательность терминов; при смене заголовка повторно проверьте входящие ссылки. Финальная проверка включает фактическую точность, самостоятельное перечитывание, link check для новых и существующих ссылок и проверку форматирования. Источник отдельно упоминает npm run format как возможную форматирующую проверку, но она должна запускаться в контексте проекта и его доступных зависимостей. Практический результат навыка — не просто длинный Markdown, а документ, который можно прочитать с экрана, связать с кодом, установить в навигацию и поддерживать после следующего изменения реализации. Ограничение очевидно: навык задаёт редакционный процесс и стандарты, но сам по себе не подтверждает бизнес-факты; каждый технический тезис всё равно нужно сверять с текущим репозиторием.