AgentSkillsCN

docs

文档生成与 Docusaurus 网站工作流、同步映射及国际化支持。

SKILL.md
--- frontmatter
name: docs
description: Documentation and Docusaurus website workflow, sync map, and i18n
disable-model-invocation: false

Docs and Website

This skill covers updating documentation and the Docusaurus website for Invowk.

Use this skill when working on:

  • •website/ - Docusaurus documentation site
  • •website/docs/ - Documentation pages
  • •website/i18n/ - Internationalization
  • •Schema changes that require documentation updates

Required Workflow

  • •Read website/WEBSITE_DOCS.md before any website edits.
  • •Use MDX + <Snippet> for all code/CLI/CUE blocks.
  • •Define snippets in website/src/components/Snippet/snippets.ts and reuse IDs across locales.
  • •Escape ${...} inside snippets as \${...}.

Documentation Sync Map

ChangeUpdate
pkg/invkfile/invkfile_schema.cuewebsite/docs/reference/invkfile-schema.mdx + affected docs/snippets
pkg/invkmod/invkmod_schema.cuewebsite/docs/modules/ pages
pkg/invkmod/operations*.gowebsite/docs/modules/ pages (validation, create, packaging, vendoring)
internal/config/config_schema.cuewebsite/docs/reference/config-schema.mdx, website/docs/configuration/options.mdx
internal/runtime/container*.gowebsite/docs/runtime-modes/container.mdx
cmd/invowk/*.gowebsite/docs/reference/cli.mdx + relevant feature docs
cmd/invowk/module*.gowebsite/docs/modules/ pages + website/docs/reference/cli.mdx
cmd/invowk/cmd_validate*.gowebsite/docs/dependencies/ pages
cmd/invowk/tui_*.gowebsite/docs/tui/ pages + snippets
New featuresAdd/update docs under website/docs/ and snippets as needed

Documentation Structure

code
website/docs/
|-- getting-started/     # Installation, quickstart, first invkfile
|-- core-concepts/       # Invkfile format, commands, implementations
|-- runtime-modes/       # Native, virtual, container execution
|-- dependencies/        # Tools, filepaths, capabilities, custom checks
|-- flags-and-arguments/ # CLI flags and positional arguments
|-- environment/         # Env files, env vars, precedence
|-- advanced/            # Interpreters, workdir, platform-specific
|-- modules/             # Module creation, validation, distribution
|-- tui/                 # TUI components reference
|-- configuration/       # Config file and options
`-- reference/           # CLI, invkfile schema, config schema

Documentation Style Guide

  • •Use a friendly, approachable tone with occasional humor.
  • •Follow progressive disclosure: start simple, add complexity gradually.
  • •Include practical examples for each feature.
  • •Use admonitions for important callouts.
  • •Keep code examples concise and focused.

Docs + i18n Checklist

  • •Always use .mdx (not .md) in website/docs/ and translations.
  • •Treat website/docs/ as the upcoming version; only touch versioned docs for backport fixes (see website/WEBSITE_DOCS.md).
  • •Update English first, then mirror the same .mdx path in website/i18n/pt-BR/docusaurus-plugin-content-docs/current/.
  • •Keep translations prose-only and reuse identical snippet IDs.
  • •Regenerate translation JSON when UI strings change: cd website && npx docusaurus write-translations --locale pt-BR.

Documentation Testing

bash
# Single locale development
cd website && npm start

# Brazilian Portuguese locale
cd website && npm start -- --locale pt-BR

# Full build (tests all locales)
cd website && npm run build

# Serve built site (for locale switching)
cd website && npm run serve

Common Pitfalls

  • •Missing i18n - Website changes require updates to both docs/ and i18n/pt-BR/.
  • •Outdated documentation - Check the Documentation Sync Map when modifying schemas or CLI.