菜单
Guides when to use the docs create/edit CLI tools versus direct file editing for InfluxData documentation. Use when deciding whether to scaffold new pages with docs create, open existing pages with docs edit, or edit Markdown files directly.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
| name | docs-cli-workflow |
| description | Guides when to use the docs create/edit CLI tools versus direct file editing for InfluxData documentation. Use when deciding whether to scaffold new pages with docs create, open existing pages with docs edit, or edit Markdown files directly. |
Help recognize when to suggest docs create or docs edit CLI tools instead of direct file editing.
These tools provide scaffolding, context gathering, and education about conventions that direct editing misses.
Check for these trigger keywords in user messages:
Skip this skill when:
docs create when| Trigger | Why CLI is better |
|---|---|
| Content targets multiple products | CLI scaffolds shared content pattern automatically |
| User unsure where page should live | CLI analyzes structure, suggests location |
| Draft references existing docs | CLI extracts links, provides context to avoid duplication |
| User seems unfamiliar with conventions | CLI prompt includes style guide, shortcode examples |
| Complex new feature documentation | CLI gathers product metadata, version info |
docs edit when| Trigger | Why CLI is better |
|---|---|
| User provides docs.influxdata.com URL | CLI finds source file(s) including shared content |
| User doesn't know source file location | CLI maps URL to file path(s) |
| Page uses shared content | CLI identifies both frontmatter file AND shared source |
| Scenario | Why direct is fine |
|---|---|
| User provides explicit file path | They already know where to edit |
| Small typo/link fixes | CLI overhead not worth it |
| User says "just edit it" | Explicit preference to skip CLI |
| Frontmatter-only changes | No content generation needed |
When a trigger is detected, present a concise recommendation and wait for confirmation.
docs createI'd recommend using the docs CLI for this:
docs create <draft-path> --products <product-key-or-path>
**Why**: [1-2 sentences explaining the specific benefit]
Options:
1. **Use CLI** - I'll run the command and guide you through product selection
2. **Edit directly** - Skip the CLI, I'll create/edit files manually
Which do you prefer?
docs editI can use the docs CLI to find the source files for this page:
docs edit <url-or-path>
**Why**: [1-2 sentences explaining the benefit]
Options:
1. **Use CLI** - I'll find and list the relevant files (non-blocking)
2. **I know the file** - Tell me the path and I'll edit directly
Which do you prefer?
| Situation | Behavior |
|---|---|
Already in a docs create workflow | Don't re-suggest |
| URL points to non-existent page | Suggest creating a draft, then run docs create --url <url> --from-draft <draft> instead of docs edit |
| User provides both URL and draft | Suggest docs create --url <url> --from-draft <draft> |
| User declines CLI twice in session | Stop suggesting, respect preference |
Run the appropriate command and let the CLI handle the rest. No additional guidance needed—the CLI manages product selection, file generation, and context gathering.
The unified docs CLI includes all documentation tooling commands.
Product targeting: --products accepts both product keys (influxdb3_core) and content paths (/influxdb3/core).
# CREATE: Create new documentation from a draft
docs create <draft-path> --products <key-or-path>
docs create <draft-path> --products /influxdb3/core,/influxdb3/enterprise
docs create <draft-path> --products influxdb3_core --open # Non-blocking
docs create --url <url> --from-draft <draft-path> # Create at URL
# EDIT: Find and edit existing documentation
docs edit <url-or-path> # Non-blocking, agent-friendly
docs edit <url-or-path> --list # List files without opening
docs edit <url-or-path> --wait # Block until editor closes
docs edit <url-or-path> --editor nano # Use specific editor
# PLACEHOLDERS: Add placeholder syntax to code blocks
docs placeholders <file.md> # Add { placeholders="PATTERN" } syntax
docs placeholders <file.md> --dry # Preview changes without writing
# AUDIT: Audit documentation coverage
docs audit --products influxdb3_core # Default version: main
docs audit --products /influxdb3/core --version v3.3.0 # Specific version
docs audit --products influxdb3_core,influxdb3_enterprise
docs audit --repos ~/github/influxdata/influxdb # Direct repo path
# RELEASE-NOTES: Generate release notes from commits
docs release-notes v3.1.0 v3.2.0 --products influxdb3_core
docs release-notes v3.1.0 v3.2.0 --products /influxdb3/core,/influxdb3/enterprise
docs release-notes v3.1.0 v3.2.0 --repos ~/repos/influxdb
# Examples
docs edit https://docs.influxdata.com/influxdb3/core/admin/databases/
docs edit /influxdb3/core/admin/databases/
docs placeholders content/influxdb3/core/admin/databases/create.md
Note: --products and --repos are mutually exclusive for audit and release-notes.
Editor Selection (checked in order):
--editor flagDOCS_EDITOR environment variableVISUAL environment variableEDITOR environment variableImportant for AI Agents:
docs edit and docs create --open commands are non-blocking by default (launch editor in background and exit immediately)--wait only when you need to block until editing is completedocs create, omit --open to skip editor entirely (files are created and CLI exits)For full CLI documentation, run docs --help.
Testing decision guide for agents working in docs-v2. Maps changed file types to the exact test commands to run, documents what runs automatically in hooks and CI, and flags coverage gaps. Load Part 1 for the decision table; load later parts only when executing a specific test type.
Create, edit, and validate InfluxData documentation. Manages Hugo shared content across InfluxDB products, runs Vale style linting and Hugo builds, validates frontmatter and code blocks, and fact-checks via the documentation MCP server. Use when creating new doc pages, editing markdown .md files, managing shared content, running Vale or Hugo builds, or testing InfluxDB, Telegraf, or Flux documentation.
Run, validate, and analyze Cypress E2E tests for the InfluxData documentation site. Covers Hugo server management, test execution modes, and failure analysis. Use when writing or running Cypress tests, verifying rendered pages, checking JSON-LD/structured data, or debugging E2E failures after template, layout, or content changes.
Capture durable goal, intent, and decisions for a unit of work as an execution plan under docs/exec-plans/. Use when finishing a non-trivial change that needs a decision record, when a PR closes one or more issues and the rationale would otherwise live only in commit messages or PR descriptions, or when the user asks to write an exec-plan, decision doc, or to document the why behind a change. Distinct from PLAN.md (ephemeral, scrubbed by CI on merge) and design-docs (architectural).
Hugo template development for InfluxData docs-v2, enforcing build and runtime testing to catch template errors that build-only validation misses. Use when creating or editing Hugo layouts, partials, or shortcodes, debugging template errors, or accessing site data in templates.
Set up InfluxDB 3 Core and Enterprise instances for running documentation code block tests. Handles service initialization, worktree-specific databases, and test environment configuration. Use when preparing to run InfluxDB 3 code block tests, starting Core or Enterprise instances, or configuring .env.test and worktree-specific test databases.