| name | docs-dev |
| argument-hint | "<page or component to work on>" |
| allowed-tools | Read, Write, Edit, Glob, Grep, Bash(npm *), Bash(cd *), mcp__playwright__* |
| description | Develop and visually verify changes to the documentation site (VitePress). Use when working on doc pages, Vue components, VitePress config, or validating docs UI with Playwright MCP. |
Skill: docs-dev
Develop and visually verify changes to the bpmn-to-code documentation site.
IMPORTANT
- VitePress conventions: Content is Markdown with VitePress extensions. Follow existing page structure.
- Vue components: Custom components live in
.vitepress/theme/. Use Vue 3 Composition API.
- Read before editing: Always read the target files before making changes to understand existing patterns.
- Build check: Always run
npm run build to catch broken links or build errors before finishing.
Instructions
Step 1 — Understand the architecture
The documentation site uses VitePress at docs/.
Key facts:
- Content: Markdown files in
docs/ (e.g. index.md for landing page)
- Config:
docs/.vitepress/config.mts — site title, navigation, sidebar, footer, social links
- Theme:
docs/.vitepress/theme/ — custom theme extending DefaultTheme
- Vue components: e.g.
VersionBadge.vue (fetches latest GitHub release, displays in nav bar)
- Custom CSS:
docs/.vitepress/theme/style.css
- Dependencies: Read versions from
docs/package.json (do not hardcode)
Step 2 — Review current state
Read the files relevant to $ARGUMENTS. Key files and their purposes:
| File | Purpose |
|---|
docs/index.md | Landing page: hero section, feature cards, code comparison |
docs/.vitepress/config.mts | Site config: nav bar, sidebar, footer, social links |
docs/.vitepress/theme/index.ts | Theme setup: extends DefaultTheme, registers components |
docs/.vitepress/theme/style.css | Custom CSS overrides |
docs/.vitepress/theme/components/*.vue | Custom Vue components |
docs/web/index.md | "Try in Browser" page linking to web module |
docs/getting-started/*.md | Gradle and Maven setup guides |
docs/engines/*.md | Engine-specific documentation |
docs/guide/*.md | Configuration and generated API guides |
docs/contributing/*.md | Contributing guide, AI skills, Docker deployment, best practices |
docs/contributing/adr/*.md | Architectural Decision Records |
Step 3 — Make changes
Follow these conventions:
- Markdown: Use VitePress frontmatter (
layout, hero, features). Use ::: containers for tips/warnings.
- Vue components: Vue 3 Composition API (
<script setup>). Register in theme/index.ts.
- Navigation: Update
config.mts themeConfig.nav and themeConfig.sidebar for new pages.
- Links: Use relative paths for internal links. External links get
target: _blank.
- Images: Store in
docs/public/ and reference with absolute paths.
Step 4 — Build and run locally
cd docs && npm run dev
cd docs && npm run build
cd docs && npm run preview
Step 5 — Visual verification (only on request)
Do not run visual verification automatically. Use AskUserQuestion to ask the user what should be verified. Only proceed with the steps below if the user or $ARGUMENTS explicitly request visual testing.
Prerequisite: Playwright MCP must be configured in the agent's MCP settings.
- Ensure the docs site is running (
cd docs && npm run dev in the background)
- Navigate to the local dev server URL
- Perform only the verification steps the user requested
- Store screenshots in
.tmp/ (gitignored). Never check screenshots into git.
- Name screenshots descriptively:
docs-{page}-{state}.png
- Clean up
.tmp/ when the skill terminates
To attach screenshots to a PR, upload them as draft release assets:
gh release create screenshots-pr-<NUMBER> --draft --title "PR #<NUMBER> Screenshots" --notes "Temporary" .tmp/*.png
gh release view screenshots-pr-<NUMBER> --json assets --jq '.assets[] | .url'
gh pr comment <NUMBER> --body ""
The draft release can be deleted after the PR is merged.
Step 6 — Report
Summarize:
- What was changed and why
- Which files were modified
- Build result (
npm run build passed/failed)
- Verification results (screenshots taken, issues found)
- Any follow-up items
