DOCX Processing Superdoc Agent Skill

SuperDoc CLI (v1)

Use SuperDoc CLI for DOCX work. Use v1 commands (canonical operations and their helper wrappers).

Do not default to legacy commands unless explicitly needed for v0-style bulk workflows.

Use superdoc if installed, or npx @superdoc-dev/cli@latest as a fallback.

First Step: Discover Exact Params

For unknown commands or flags, inspect runtime metadata first:

superdoc describe
superdoc describe command find
superdoc describe command "comments add"

Use describe command for per-command args and constraints.

Preferred Workflows

1) Stateful multi-step edits (recommended)

superdoc open ./contract.docx
superdoc query match --select-json '{"type":"text","pattern":"termination"}' --require exactlyOne
superdoc replace --target-json '{"kind":"text","blockId":"p1","range":{"start":0,"end":11}}' --text "expiration"
superdoc save --in-place
superdoc close

• Always use query match (not find) to discover mutation targets — it returns exact addresses with cardinality guarantees.
• After open, commands run against the active/default session when <doc> is omitted.
• Use superdoc session list|set-default|save|close for explicit session control.
• close on dirty state requires --discard or a prior save.

2) Stateless one-off reads

superdoc get-text ./proposal.docx
superdoc get-markdown ./proposal.docx
superdoc info ./proposal.docx

3) Stateless one-off mutations

superdoc replace ./proposal.docx \
  --target-json '{"kind":"text","blockId":"p1","range":{"start":0,"end":5}}' \
  --text "Updated" \
  --out ./proposal.updated.docx

• In stateless mode (<doc> provided), mutating commands require --out unless using --dry-run.

Safety: preview before apply

• Use --dry-run to preview any mutation without applying it.
• Use --expected-revision <n> with stateful mutations for optimistic concurrency checks.

Common v1 Commands

Query & inspect

• Search/browse content: find --type text --pattern "..." or find --query-json '{...}'
• Find mutation target: query match --select-json '{...}' --require exactlyOne
• Inspect blocks: blocks list, get-node, get-node-by-id
• Extract content: get-text, get-markdown, get-html

Mutate

• Replace text: replace --target-json '{...}' --text "..."
• Insert inline text: insert --block-id <id> --offset <n> --value "..."
• Delete text/node: delete --target-json '{...}'
• Delete blocks: blocks delete, blocks delete-range
• Batch mutations: mutations apply --steps-json '[...]' --atomic true --change-mode direct
• Create paragraph: create paragraph --text "..." (with optional --at-json)
• Create heading: create heading --input-json '{"level":<n>,"text":"..."}'

Format

• Apply formatting: format apply --block-id <id> --start <n> --end <n> --inline-json '{"bold":true}'
• Shortcuts: format bold, format italic, format underline, format strikethrough

Lists

• List items: lists list, lists get
• Insert list item: lists insert --node-id <id> --position after --text "..."
• Modify: lists indent, lists outdent, lists set-level, lists set-type, lists convert-to-text

Comments

• Add/reply: comments add, comments reply
• Read: comments get, comments list
• Edit/resolve/move: comments edit, comments resolve, comments move, comments set-internal
• Delete: comments delete (canonical) or comments remove (alias)

Track changes

• List: track-changes list, track-changes get
• Decide: track-changes accept, track-changes reject, track-changes accept-all, track-changes reject-all

History

• history get, history undo, history redo

Low-level

• Direct invoke: call <operationId> --input-json '{...}' (JSON output only — --pretty is not supported)

JSON/File Payload Flags

Not all --*-file variants are available on every command. Use describe command <name> to check.

Always supported alongside their -json counterpart (use one, not both):

| Flag pair | Available on |

|-----------|-------------|

| --query-json / --query-file | find, lists list |

| --address-json / --address-file | get-node, lists get |

| --input-json / --input-file | call, create paragraph |

| --at-json / --at-file | create paragraph |

--target-json is widely available on mutation commands but has no --target-file counterpart. Use flat flags (--block-id, --start, --end) as an alternative to --target-json.

Output and Global Flags

• Default output is JSON envelope.
• Use --pretty for human-readable output (not supported by call).
• Global flags: --output <json|pretty>, --session <id>, --timeout-ms <n>.
• <doc> can be - to read DOCX bytes from stdin.

Legacy Compatibility (Use Sparingly)

Legacy v0.x bridge commands still exist:

superdoc search <pattern> <files...>
superdoc replace-legacy <find> <to> <files...>
superdoc read <file>

Use these only when you specifically need v0-style behavior (especially multi-file glob search/replace).

For new automations, prefer v1 operations.