---

name: docs-cli-workflow description: Guides when to use docs create/edit CLI tools versus direct file editing for InfluxData documentation. author: InfluxData version: "1.0"

docs CLI Workflow Guidance

Purpose

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.

When This Skill Applies

Check for these trigger keywords in user messages:

• "new page", "new doc", "create documentation", "add a page"
• "edit this URL", "edit https://docs", "update this page" (with a URL)
• "document this feature", "write docs for"
• "I have a draft", "from this draft"
• Any docs.influxdata.com URL

Skip this skill when:

• User provides an explicit file path (e.g., "fix typo in content/influxdb3/...")
• Small fixes (typos, broken links)
• User says "just edit it" or similar
• Frontmatter-only changes

Decision: Which Tool to Suggest

Suggest docs create when

Suggest docs edit when

Edit directly when

How to Suggest

When a trigger is detected, present a concise recommendation and wait for confirmation.

For docs create

CopyI'd recommend using the docs CLI for this:

npx docs create <draft-path> --products <product>

**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?

For docs edit

CopyI 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?

Key principles

• Show the actual command (educational)
• Explain why for this specific case
• Always offer the direct alternative
• Keep it brief (4-6 lines max)
• Wait for user confirmation before running

Edge Cases

After User Confirms

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.

CLI Reference

Copy# Create new documentation from a draft
npx docs create <draft-path> --products <product-key>

# Create and open files in editor (non-blocking)
npx docs create <draft-path> --products <product-key> --open

# Create and open, wait for editor (blocking)
npx docs create <draft-path> --products <product-key> --open --wait

# Create at specific URL location
npx docs create --url <url> --from-draft <draft-path>

# Find and list files for an existing page (non-blocking, agent-friendly)
docs edit <url-or-path>
docs edit <url-or-path> --list        # List files without opening editor

# Interactive editing (blocks until editor closes)
docs edit <url-or-path> --wait

# Use specific editor
docs edit <url-or-path> --editor nano

# Examples (both full URL and path work)
docs edit https://docs.influxdata.com/influxdb3/core/admin/databases/
docs edit /influxdb3/core/admin/databases/

Editor Selection (checked in order):

1. --editor flag
2. DOCS_EDITOR environment variable
3. VISUAL environment variable
4. EDITOR environment variable
5. System default

Important for AI Agents:

• Both docs edit and docs create --open commands are non-blocking by default (launch editor in background and exit immediately)
• This prevents agents from hanging while waiting for user editing
• Use --wait only when you need to block until editing is complete
• For docs create, omit --open to skip editor entirely (files are created and CLI exits)

For full CLI documentation, run npx docs --help.

Related Skills

• hugo-template-dev - For Hugo template syntax, data access patterns, and runtime testing
• cypress-e2e-testing - For running and debugging Cypress E2E tests
• ts-component-dev (agent) - TypeScript component behavior and interactivity