135 lines
5.0 KiB
Markdown
135 lines
5.0 KiB
Markdown
# docs-cli-workflow Skill Design
|
|
|
|
## Overview
|
|
|
|
A Claude Code skill that guides when to use `docs create` and `docs edit` CLI tools versus direct file editing for InfluxData documentation.
|
|
|
|
## Problem
|
|
|
|
Claude under-utilizes the `docs create` and `docs edit` CLI tools even when they would provide significant value:
|
|
|
|
- Better scaffolding for multi-product content
|
|
- Context gathering (link extraction, structure analysis)
|
|
- Education about style guidelines and shortcodes
|
|
- Automatic file location from URLs
|
|
|
|
## Skill Identity
|
|
|
|
- **Name**: `docs-cli-workflow`
|
|
- **Location**: `.claude/skills/docs-cli-workflow/SKILL.md`
|
|
- **Scope**: Decision guidance only (not full workflow management)
|
|
- **Behavior**: Suggest and wait for user confirmation
|
|
|
|
## Activation
|
|
|
|
### Trigger Keywords
|
|
|
|
The skill activates when user messages contain:
|
|
|
|
- "new page", "new doc", "create documentation", "add a page"
|
|
- "edit this URL", "edit <https://docs>", "update this page" (with URL)
|
|
- "document this feature", "write docs for"
|
|
- "I have a draft", "from this draft"
|
|
- References to docs.influxdata.com URLs
|
|
|
|
### Non-Triggers (Direct Editing is Fine)
|
|
|
|
- "fix this typo in content/..."
|
|
- "update the frontmatter in..."
|
|
- Explicit file paths the user already knows
|
|
- Small edits to existing files user has open
|
|
|
|
## Decision Logic
|
|
|
|
### When to Suggest `docs create`
|
|
|
|
| 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 unfamiliar with conventions | CLI prompt includes style guide, shortcode examples |
|
|
| Complex new feature documentation | CLI gathers product metadata, version info |
|
|
|
|
### When to Suggest `docs edit`
|
|
|
|
| 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 → file path(s) |
|
|
| Page uses shared content | CLI identifies both frontmatter file AND shared source |
|
|
|
|
### When to Skip CLI (Edit Directly)
|
|
|
|
| Scenario | Why Direct is Fine |
|
|
| -------------------------------- | ------------------------------- |
|
|
| User provides explicit file path | They already know where to edit |
|
|
| Small typo/link fixes | Overhead not worth it |
|
|
| User says "just edit it" | Explicit preference |
|
|
| Frontmatter-only changes | No content generation needed |
|
|
|
|
## Suggestion Format
|
|
|
|
### For `docs create`
|
|
|
|
```
|
|
I'd recommend using the docs CLI for this:
|
|
|
|
npx docs create <draft-path> --products <product>
|
|
|
|
**Why**: [1-2 sentences explaining the specific benefit for this request]
|
|
|
|
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`
|
|
|
|
```
|
|
I can use the docs CLI to find the source files for this page:
|
|
|
|
npx docs edit <url>
|
|
|
|
**Why**: [1-2 sentences - e.g., "This will locate the source file and any shared content it uses"]
|
|
|
|
Options:
|
|
1. **Use CLI** - I'll find and open the relevant files
|
|
2. **I know the file** - Tell me the path and I'll edit directly
|
|
|
|
Which do you prefer?
|
|
```
|
|
|
|
### Principles
|
|
|
|
- Show the actual command (educational)
|
|
- Explain *why* for this specific case
|
|
- Always offer the direct alternative
|
|
- Keep it brief - 4-6 lines max
|
|
|
|
## Edge Cases
|
|
|
|
| Edge Case | Behavior |
|
|
| ---------------------------------------- | ------------------------------------------------------ |
|
|
| User already in a `docs create` workflow | Don't re-suggest |
|
|
| URL points to non-existent page | Suggest `docs create --url` 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, note preference |
|
|
|
|
## Post-Confirmation Behavior
|
|
|
|
After user confirms they want to use the CLI:
|
|
|
|
1. Run the appropriate command
|
|
2. Let the CLI handle the rest (product selection, file generation, etc.)
|
|
3. No additional skill guidance needed
|
|
|
|
## Related Files
|
|
|
|
- `scripts/docs-cli.js` - Main CLI entry point
|
|
- `scripts/docs-create.js` - Content scaffolding implementation
|
|
- `scripts/docs-edit.js` - File finder implementation
|
|
- `scripts/lib/content-scaffolding.js` - Context preparation logic
|