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

dart-doc-validation — скилл для Claude Code

Скилл dart-doc-validation учит агента проверять комментарии документации в Dart-коде командой dart doc и включать линт comment_references, чтобы ловить битые ссылки на классы, методы и макросы.

Apache-2.0 291 установок ★ 149 обновлён 2026-10-17

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

Что делает dart-doc-validation

Скилл настраивает валидацию документационных комментариев в Dart-проектах. Агент запускает dart doc -o $(mktemp -d) для поиска неразрешённых ссылок (unresolved doc reference) и неопределённых макросов (undefined macro), включает линт comment_references в analysis_options.yaml и объясняет, как исправить типовые предупреждения.

Внутри — команда для локальной проверки без захламления рабочей директории, инструкция по настройке локального HTTP-сервера через dhttpd для просмотра сгенерированных страниц и правило воздержания: агент не трогает псевдокод, сгенерированные файлы вроде *.g.dart и внешние Markdown-ссылки.

Подходит для подготовки пакета к публикации на pub.dev и поддержания порядка в документации. Без FFmpeg, Python или сторонних библиотек — работает на встроенных средствах Dart SDK.

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

  • проверить Dart-документацию на битые ссылки перед публикацией на pub.dev
  • включить линт comment_references в analysis_options.yaml
  • запустить dart doc локально, не засоряя рабочую директорию
  • исправить предупреждения unresolved doc reference и undefined macro
  • настроить локальный HTTP-сервер для просмотра сгенерированной документации

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

  • Включи линт comment_references в analysis_options.yaml и проверь документацию командой dart doc
  • Запусти валидацию Dart-комментариев без сохранения файлов в проект
  • Покажи, как исправить предупреждение unresolved doc reference в src/models.dart

Как установить dart-doc-validation

1Через Skills CLI (Vercel)

npx skills add kevmoo/dash_skills --skill dart-doc-validation -a claude-code

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

~/.claude/skills/dart-doc-validation/SKILL.md

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

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

Вопросы о dart-doc-validation

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

Выполни npx skills add kevmoo/dash_skills --skill dart-doc-validation -a claude-code, затем проверь файл ~/.claude/skills/dart-doc-validation/SKILL.md.

Что делает dart-doc-validation?

Скилл учит агента валидировать документационные комментарии в Dart-коде: запускать dart doc для поиска битых ссылок и макросов, включать линт comment_references и исправлять типовые предупреждения.

Когда dart-doc-validation не применяется?

Скилл не трогает псевдокод, сгенерированные файлы (*.g.dart, *.freezed.dart), внешние Markdown-ссылки и фрагменты на языках вне Dart (YAML, JSON, Bash).

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

SKILL.md · Apache-2.0
---
name: dart-doc-validation
description: |-
  Best practices for validating Dart documentation comments.
  Covers using `dart doc` to catch unresolved references and macros.
license: Apache-2.0
key_features:
  - Documentation comment validation
  - Unresolved reference checking
  - Dart doc macro verification
---

# Dart Doc Validation

## 1. When to use this skill

Use this skill when:

- Writing or updating documentation comments (`///`) in Dart code.
- Checking for broken documentation links, references, or macros.
- Preparing a package for publishing to pub.dev.

### When NOT to use (Abstention Guardrails)

Do NOT apply this skill or refactor doc comments when:

- **Illustrative Pseudo-Code & Non-Dart Code Fences**: Comments contain
  pseudo-code, non-Dart language identifiers (e.g. ``yaml`, ``json`, ````bash`,
  ````text`), or abstract conceptual fragments intentionally not designed to
  compile as valid Dart.
- **Generated Code**: Files generated by tools (e.g. `*.g.dart`, `*.mocks.dart`,
  `*.freezed.dart`) where comments are synthesized.
- **External Markdown Hyperlinks**: Text in square brackets followed by a link
  target (e.g. `[External Guide](https://...)`), which is standard Markdown
  hyperlink syntax rather than an unresolved Dart doc reference.

## Discovery

To find documentation issues:

### Missing Lint

Verify if the `comment_references` lint is enabled:

- **Target**: `analysis_options.yaml`
- **Search Query**: `comment_references`

### Automated Validation

Run the documentation generator to surface warnings:

- **Command**: `dart doc -o $(mktemp -d)`
- **Keywords to look for**: `warning:`, `unresolved doc reference`,
  `undefined macro`

## 2. Best Practices

### Enable the doc validation lint

In your `analysis_options.yaml`, enable the `comment_references` lint.

```yaml
linter:
  rules:
    - comment_references
```

### Validating Documentation Locally

Use the `dart doc` command with a temporary output directory to validate
documentation comments without polluting the local project workspace.

This command parses all documentation comments and reports warnings such as:

- `warning: unresolved doc reference`
- `warning: undefined macro`

**Command to run:**

```bash
dart doc -o $(mktemp -d)
```

_This will work on Mac and Linux._

This ensures that the generated HTML files are stored in a temporary location
and don't clutter the package directory, while still surfacing all validation
warnings in the terminal output.

**Browsing the docs:**

Our docs use features designed to be run on a web server. If you want to browse
the generated docs locally, install the `dhttpd` package.

```shell
dart install dhttpd
TMP_DIR=$(mktemp -d) && dart doc -o "$TMP_DIR" &&  dhttpd --path "$TMP_DIR"
```

_(Or use another HTTP server, such as `python3 -m http.server`.)_

### Fixing Common Warnings

- **Unresolved doc reference**: Ensure that any identifier wrapped in square
  brackets (`[Identifier]`) correctly points to an existing class, method,
  property, or parameter in the current scope or imported libraries.
- **Undefined macro**: If using `{@macro macro_name}`, ensure that the template
  `{@template macro_name}` is defined in the same file or a file that is
  imported and visible to the documentation generator.

© kevmoo · Apache-2.0 · kevmoo/dash_skills

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

Все скиллы по теме «Тексты и документация» →
dart-use-doc-examples flutter Скилл dart-use-doc-examples учит агента вставлять внешние примеры кода в Dartdoc через директиву {@example} вместо inline-блоков. CX Codex +1 9 200установок dart-write-documentation flutter Скилл dart-write-documentation для Claude Code описывает правила оформления API-документации в Dart: тройные слэши, порядок аннотаций, ссылки в квадратных скобках и запрет Javadoc-тегов. CX Codex +1 11 500установок effective-dart Ivanna Kaceviča Скилл effective-dart задаёт правила чистого кода на Dart и Flutter: стиль имён, явные типы, оформление документации и структуру тестов. CX Codex +1 ★ 674звёзд репо md-validation haowjy Скилл md-validation для Claude Code проверяет ссылки в Markdown и синтаксис Mermaid. Запускайте его после правок документации, до коммита. CX Codex +1 441установок dart-add-unit-test dart-lang Скилл dart-add-unit-test для Claude Code, Codex и других агентов пишет и организует юнит-тесты на package:test. Включается при добавлении логики или исправлении багов, чтобы избежать регрессий. CX Codex +1 21 400установок dart-fix-runtime-errors dart-lang Скилл dart-fix-runtime-errors автоматически ловит ошибки времени выполнения в Dart-коде, находит проблемную строку через LSP и стек-трейс, применяет исправление и проверяет результат через hot reload. CX Codex +1 20 800установок

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

dart-best-practices Скилл dart-best-practices задаёт правила оформления кода на Dart при генерации и ревью. Помогает форматировать многострочные блоки и соблюдать лимит длины строки в 80 знаков. CX Codex +1 847установок dart-test-fundamentals Скилл dart-test-fundamentals для Claude Code и Codex задаёт стандарты работы с библиотекой package:test в Dart. Инструмент следит за структурой тестов, вызовами setUp и очисткой ресурсов через addTearDown. CX Codex +1 455установок dart-modern-features Скилл dart-modern-features обучает агента современному синтаксису Dart версий 3.0–3.10. Он помогает безопасно внедрять записи, extension types и модификаторы классов при рефакторинге. CX Codex +1 370установок dart-package-maintenance Скилл dart-package-maintenance для Claude Code помогает вести Dart-пакеты: следить за версиями, синхронизировать CHANGELOG и управлять релизами. Описывает поддержку пакетов на pub.dev. CX Codex +1 285установок dart-matcher-best-practices Скилл dart-matcher-best-practices для Claude Code помогает писать проверки Dart через expect и package:matcher. Он подключается при создании тестов, разборе сбоев и замене ручных проверок. CX Codex +1 269установок dart-test-coverage Скилл dart-test-coverage для Claude Code запускает сбор покрытия Dart-пакета, разбирает пропущенные строки и помогает наметить тесты. Помогает выявить непроверенный код в lib/. CX Codex +1 163установок dart-long-lines Скилл dart-long-lines для Claude Code помогает соблюдать лимит в 80 символов в строках Dart. Он подключается при написании и рефакторинге кода под lint lines_longer_than_80_chars. CX Codex +1 150установок dart-multiline-strings Скилл dart-multiline-strings для Claude Code учит переписывать цепочки print() и конкатенации в тройные кавычки. Запускается при рефакторинге CLI-вывода, шаблонных сообщений и многострочных блоков в Dart. CX Codex +1 116установок

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

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