OpenParable
Skip to content
← Back to skills

Documentation Workflow

Business
documentation-workflow

Documentation Workflow is an Agent Skill for business published in the massCodeIO/massCode repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when adding or updating massCode documentation, documenting a new feature, changing docs website pages, adding docs assets, updating the VitePress sidebar, or adding README feature mentions.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/massCodeIO/massCode/blob/HEAD/.agents/skills/documentation-workflow/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/documentation-workflow, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Documentation Workflow

Overview

Документация massCode живёт в VitePress сайте в docs/website/documentation. README — это общий обзор проекта, а не источник детального описания фич.

Documentation Surfaces

  • Документация фич: docs/website/documentation/**
  • Sidebar документации: docs/website/.vitepress/config.mts
  • Assets документации: docs/website/public/**
  • Overview документации: docs/website/documentation/index.md
  • Overview проекта: README.md

Core Rules

  • Проверяй поведение фичи в коде или существующей документации; не документируй по памяти.
  • Используй rg, чтобы найти связанные страницы, скриншоты, shortcuts, labels и существующие формулировки.
  • Если целевая версия известна, используй именно её. Если версия неизвестна, не придумывай её.
  • Пользовательская документация сайта пишется на английском, в стиле существующих docs pages.
  • Добавляй или обновляй наиболее конкретную страницу в docs/website/documentation.
  • Для новых страниц используй frontmatter с title и description.
  • Если фича доступна только с конкретного релиза, добавляй <AppVersion text=">=x.y" /> ближе к началу страницы.
  • Добавляй страницу в docs/website/.vitepress/config.mts только если она должна появиться в навигации.
  • Ссылайся из docs/website/documentation/index.md только на широкие, cross-cutting фичи.
  • Пиши короткими task-oriented секциями. Предпочитай пользовательские флоу, а не детали реализации.
  • Shortcuts документируй через <kbd>...</kbd> и указывай macOS плюс Windows/Linux варианты, если они отличаются.

VitePress Markdown Gotchas

  • VitePress компилирует markdown как Vue-компонент, поэтому {{ ... }} трактуется как Vue-интерполяция и исчезает из вывода.
  • Fenced-блоки (```) защищены автоматически — внутри них {{var}} рендерится буквально.
  • Инлайн-код в backticks НЕ защищён: `{{variables}}` отрендерится пустым. Чтобы вывести литеральные двойные фигурные скобки в тексте или таблице, оборачивай в v-pre: <code v-pre>{{variables}}</code>
  • Это же касается любых других Vue-конструкций ({{ }}, директивы) в произвольном тексте страницы.

Images And Assets Rules

  • Картинки для docs клади в docs/website/public.
  • Ссылайся на картинки через withBase, например: <img :src="withBase('/feature.png')">
  • Если страница использует withBase, добавь соответствующий script block: import { withBase } from 'vitepress'
  • Используй скриншоты только когда они реально объясняют фичу. Не добавляй декоративные изображения.

README Rules

  • Добавляй README-упоминания только для user-facing фич, которые важны на уровне общего обзора проекта.
  • Держи README copy коротким и product-level; подробное использование должно быть в docs/website/documentation.
  • Не пиши в README, когда фича была добавлена. Version availability должна жить в docs pages или release notes.
  • Не ставь новую фичу первой автоматически. Сохраняй текущую информационную архитектуру: сначала основные spaces/features, затем широкие workflow helpers, если пользователь не попросил иначе.

Validation

  • Запускай git diff --check.
  • Для изменений docs website запускай pnpm -C docs/website build.
  • Если нужно форматирование, ограничивай его изменёнными файлами и избегай широкого churn в config-файлах.
  • Не коммить без явной просьбы пользователя. Для commit или PR загружай github-workflow.

Common Mistakes

  • Добавлять README-only документацию для фичи, которой нужна настоящая docs page.
  • Забывать VitePress sidebar для новой страницы, которая должна быть в навигации.
  • Добавлять version availability в README.
  • Документировать shortcuts или поведение без проверки реализации.
  • Запускать широкие formatters, которые переписывают существующий стиль docs config.
  • Писать литеральные {{ ... }} в инлайн-коде без v-pre — VitePress съест их как Vue-интерполяцию.