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

dart-write-documentation — скилл для Claude Code

Скилл dart-write-documentation для Claude Code описывает правила оформления API-документации в Dart: тройные слэши, порядок аннотаций, ссылки в квадратных скобках и запрет Javadoc-тегов.

BSD-3-Clause 11 500 установок ★ 3 197 обновлён 2026-10-21

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

Что делает dart-write-documentation

Скилл учит агента писать doc-комментарии по гайдлайнам Effective Dart. Все комментарии — через ///, без блочных /** */. Первый абзац — одно предложение, которое dartdoc выводит в списках. Параметры и исключения вплетаются в текст прозой: теги @param, @return, @throws запрещены. Для ссылок на идентификаторы используются квадратные скобки [ClassName], для ключевых слов — backticks.

Для конструктора по умолчанию пишется [ClassName.new], а не [ClassName()]. Комментарий ставится перед аннотациями вроде @override. Если геттер и сеттер идут парой, документация размещается только на геттере. Скилл подскажет, когда наследовать документацию базового класса, и проверит, что все ссылки разрешаются через dart analyze.

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

  • оформить doc-комментарии для публичного API Dart-библиотеки
  • заменить Javadoc-теги на prose-описания параметров и исключений
  • расставить ссылки на классы и методы так, чтобы dartdoc их разрешил
  • выбрать правильный opener для свойства, булевого флага или метода
  • проверить порядок комментария и аннотаций перед @override

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

  • Документируй класс UserRepository по правилам Effective Dart
  • Добавь doc-комментарии к методам в lib/services/auth.dart
  • Перепиши документацию load без тегов @param и @return

Как установить dart-write-documentation

1Через Skills CLI (Vercel)

npx skills add flutter/agent-plugins --skill dart-write-documentation -a claude-code

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

~/.claude/skills/dart-write-documentation/SKILL.md

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

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

Вопросы о dart-write-documentation

Как установить dart-write-documentation в Claude Code?

Выполни npx skills add flutter/agent-plugins --skill dart-write-documentation -a claude-code. Файл скилла появится в ~/.claude/skills/dart-write-documentation/SKILL.md.

Что делает dart-write-documentation?

Скилл учит агента оформлять API-документацию для Dart: использовать ///, вплетать параметры и исключения в текст вместо Javadoc-тегов, ссылаться на идентификаторы в квадратных скобках и ставить комментарий перед аннотациями.

Почему нельзя использовать теги @param и @return в Dart?

Dartdoc не поддерживает Javadoc-теги. Имена параметров, возвращаемые значения и исключения описываются прозой с квадратными скобками для ссылок на идентификаторы.

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

SKILL.md · BSD-3-Clause
---
name: dart-write-documentation
description: "Rules and formatting guidelines for writing Dart /// API documentation and doc comments. Use when documenting Dart code, writing doc comments for any Dart declaration (libraries, classes, methods, variables, etc.), or when instructed to follow the Effective Dart documentation guidelines."
---

# Writing Dart API Documentation

## Contents
*   [1. Scope and Structure](#1-scope-and-structure)
*   [2. Tone and Openers](#2-tone-and-openers)
*   [3. Strict Anti-Patterns (Banned)](#3-strict-anti-patterns-banned)
*   [4. Technical Placement & Resolution](#4-technical-placement--resolution)
*   [5. Linking and Markdown](#5-linking-and-markdown)
*   [6. Verification](#6-verification)
*   [Examples](#examples)

When asked to write or update documentation for Dart code, you must strictly follow these formatting rules based on the "Effective Dart: Documentation" guidelines.

## 1. Scope and Structure
*   **Target Public APIs:** Focus your documentation efforts on public declarations. Do not document private members (those starting with an underscore `_`) unless explicitly instructed, as they do not appear in generated API reference sites.
*   **Always use `///`:** Use `///` consecutive line comments for all API documentation. Never use `/** ... */` block comments.
*   **Proper Sentences:** Format all comments like proper sentences. Capitalize the first word (unless it's a lowercase identifier) and end with a period.
*   **The First Paragraph:** The first paragraph of a doc comment must be a single, concise sentence that summarizes the element. End it with a period. Dartdoc extracts this verbatim for list views.
*   **Separation:** Always separate the first sentence summary from the rest of the documentation with a blank line containing `///`. Never output a completely empty newline (e.g., a `\n` without `///`), as this terminates the doc comment block.

## 2. Tone and Openers
*   **Noun phrases for properties:** Start descriptions of variables, getters, or setters with a noun phrase.
    `/// The radius of the sphere.` (Not "Gets the radius...")
*   **"Whether" for booleans:** Start documentation for boolean properties with "Whether".
    `/// Whether the connection is active.`
*   **Third-person verbs for methods:** Start descriptions of methods or functions with a third-person verb that describes what it does.
    `/// Initializes the database.` (Not "Initialize" or "This method initializes").
*   **Avoid redundancy:** Do not restate the signature or the element name. Do not say "This class is a..." or "The foo method does...".

## 3. Strict Anti-Patterns (Banned)
*   **No Javadoc/TSDoc Tags (`@param`, `@return`, `@throws`, etc.):** Never use Javadoc-style tags (`@param`, `@return`, `@returns`, `@throws`, `@exception`, `@see`, `@type`). Instead, weave parameter names, return behavior, and exceptions into the prose.

## 4. Technical Placement & Resolution
*   **Annotations (`@override`, etc.):** Doc comments must be placed before metadata annotations.
*   **Inherited Documentation:** Avoid duplicating doc comments on `@override` members if the behavior does not differ from the superclass or interface. Dartdoc automatically inherits the base documentation.
*   **Getter/Setter Pairs:** If a property has both a getter and a setter, place the documentation only on the getter. Tooling will emit a warning if both are documented.
*   **Default Constructors:** To link to a default, unnamed constructor in doc comments, you must use the `.new` syntax (e.g., `[ClassName.new]`).

## 5. Linking and Markdown
*   **Square brackets (`[identifier]`) for in-scope symbols:** Use square brackets to link to any in-scope identifier (parameters, classes, methods, fields, and top-level functions) so dartdoc can resolve them. Never use backticks for parameters.
*   **No parentheses in method links:** Avoid parentheses in links (e.g., use `[String.contains]`, not `[String.contains()]`).
*   **Backticks for keywords & literals:** Use backticks for keywords, literals, and arbitrary expressions (e.g. `` `null` ``, `` `true` ``, `` `void` ``). Never put keywords in square brackets (avoid `[null]` or `[true]`).
*   **Out-of-Scope Links:** If you need to link to a symbol that is not imported by the current library, use the `@docImport` directive at the top of the file (on the `library;` declaration) rather than adding a standard `import`.
*   **Code Blocks:** For code samples, always label the language fence. Use ```` ```dart ```` for Dart, or ```` ```sh ```` for shell commands. Do not leave code blocks unlabelled, as Dartdoc will attempt to auto-detect the language and frequently guesses wrong.
*   **Formatting:** Use standard Markdown (bold, lists, etc.) after the first paragraph to fully explain edge cases, exceptions thrown, and internal behavior the caller cannot see.

## 6. Verification
After writing or updating doc comments:
1. Run `dart analyze` to ensure all bracketed references resolve properly without triggering `comment_references` warnings.
2. (Optional) Run `dart doc` to verify the generated documentation renders cleanly.

## Examples

### 1. Banned Tags vs. Prose
**Bad:**
```dart
/// This method fetches data.
/// @param force true to force reload.
/// @return the data
/// @throws NetworkException if host is unreachable.
Data load(bool force) { ... }
```
**Good:**
```dart
/// Fetches the remote data.
///
/// If [force] is true, this bypasses the local cache and forces a
/// network request.
///
/// Throws a [NetworkException] if the host is unreachable.
Data load(bool force) { ... }
```

### 2. The Annotation Placement Trap
**Bad:**
```dart
@override
/// Renders the widget to the screen.
Widget build(BuildContext context) { ... }
```
**Good:**
```dart
/// Renders the widget to the screen.
@override
Widget build(BuildContext context) { ... }
```

### 3. Openers and Tone
**Bad:**
```dart
/// Gets if the connection is active.
bool get isActive => _active;

/// This method initializes the connection.
void init() { ... }
```
**Good:**
```dart
/// Whether the connection is active.
bool get isActive => _active;

/// Initializes the connection.
void init() { ... }
```

### 4. Constructor Linking
**Bad:**
```dart
/// Creates a new user. Similar to calling [User()].
User.create() { ... }
```
**Good:**
```dart
/// Creates a new user. Similar to calling [User.new].
User.create() { ... }
```

### 5. Out-of-Scope Links (@docImport)
**Bad:**
```dart
import 'package:http/http.dart'; // Adds unnecessary runtime dependency just for docs

/// To use this, you must pass a [Client].
```
**Good:**
```dart
/// @docImport 'package:http/http.dart';
library;

/// To use this, you must pass a [Client].
```

© flutter · BSD-3-Clause · flutter/agent-plugins

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

Все скиллы по теме «Тексты и документация» →
dart-doc-validation kevmoo Скилл dart-doc-validation учит агента проверять комментарии документации в Dart-коде командой dart doc и включать линт comment_references, чтобы ловить битые ссылки на классы, методы и макросы. CX Codex +1 291установок dart-add-unit-test dart-lang Скилл dart-add-unit-test для Claude Code, Codex и других агентов пишет и организует юнит-тесты на package:test. Включается при добавлении логики или исправлении багов, чтобы избежать регрессий. CX Codex +1 21 400установок dart-run-static-analysis dart-lang Скилл dart-run-static-analysis запускает dart analyze для поиска ошибок и dart fix --apply для автоисправления предупреждений линтера. Помогает проверять качество кода на Dart перед коммитами. CX Codex +1 21 200установок documentation-and-adrs addyosmani Скилл documentation-and-adrs для Claude Code фиксирует архитектурные решения и помогает находить устаревшую документацию. Подключается при изменении публичного API, выпуске функций и проверке соответствия документов коду. CX Codex +1 80 700установок flutter-dart-code-review affaan-m Скилл flutter-dart-code-review для Claude Code даёт чек-лист ревью Flutter/Dart-кода по виджетам, состоянию, идиомам, производительности и безопасности. CX Codex +1 6 600установок dart-flutter-patterns affaan-m Скилл dart-flutter-patterns для Claude Code и Codex: готовые паттерны Dart и Flutter — null safety, состояние, навигация, сеть. Ускоряет написание и ревью кода на Flutter. CX Codex +1 6 400установок

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

Весь набор →
flutter-add-widget-preview Скилл flutter-add-widget-preview для Claude Code обучает агента создавать интерактивные превью виджетов Flutter через package:flutter/widget_previews.dart. Превью позволяют верстать UI изолированно, без сборки всего приложения. CX Codex +1 40 000установок flutter-setup-localization Скилл flutter-setup-localization автоматизирует инициализацию поддержки многоязычности в Flutter-проекте. Добавляет зависимости, включает генерацию кода и создаёт конфиг для работы с .arb-файлами. CX Codex +1 39 900установок flutter-use-http-package Скилл flutter-use-http-package для Claude Code добавляет в Flutter запросы к REST API через пакет http и обработку JSON-ответов. Загружает и отправляет данные. CX Codex +1 39 100установок dart-use-primary-constructors Скилл dart-use-primary-constructors учит агента переводить классы Dart на первичные конструкторы и синтаксис Dart 3.13+. Он пригодится при рефакторинге моделей данных и сокращении шаблонного кода. CX Codex +1 17 000установок dart-use-ffigen Скилл dart-use-ffigen для Claude Code настраивает генерацию FFI-привязок через package:ffigen. Он подключается к задачам с новыми привязками или интеграциями C, Objective-C и Swift. CX Codex +1 16 800установок dart-setup-ffi-assets Скилл dart-setup-ffi-assets для Claude Code автоматизирует компиляцию и упаковку кода C/C++ в библиотеки через Native Assets в Dart. Задача — интеграция нативного кода в Flutter и Dart-пакеты. CX Codex +1 16 700установок dart-use-doc-examples Скилл dart-use-doc-examples учит агента вставлять внешние примеры кода в Dartdoc через директиву {@example} вместо inline-блоков. CX Codex +1 9 200установок dart-use-path-package Скилл dart-use-path-package учит агента работать с путями файлов в Dart через package:path, избегая строковых операций, которые ломаются на Windows. CX Codex +1 8 800установок

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

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