soia-dev-officecli-ops

soia-dev-officecli-ops

Wrap OfficeCLI into an atomic Office file operation layer that upper-level skills can reuse. It handles environment checks, structural reading, stable targeting, modify-after-copy, OpenXML validation, and preview evidence; it does not decide content, narrative, branding, or visual direction for upper-level workflows.

Customer-readable description

What this skill can do

Customer wants	Skill will do	Customer can see
Inspect Word, Excel, or PPT	Extract structure, text, statistics, and issues, and render HTML/screenshots when necessary	Issue list, element paths, previews, and fix suggestions
Precisely modify existing Office files	Prefer stable ID/name targeting, execute on a copy set/add/remove/move/swap	New file, modification receipt, validation results
Execute multiple modifications at once	Organize 3 or more operations into an atomic batch	Succeeded/failed steps; do not deliver a half-finished product on failure
Create basic Office files	Create DOCX/XLSX/PPTX structures and add content step by step	Office files that can continue to be edited
Provide an Office foundation for other skills	Choose OfficeCLI, Open Design, or host-native tools based on host capabilities and task type	Clear execution route and fallback explanation

How customers use it

1. Provide .docx、.xlsx or .pptx path, and state whether to inspect, create, or modify.
2. When modifying an existing file, also specify the output path; by default a copy is generated and the source file is not overwritten in place.
3. The Agent first runs queries on a temporary copy, then shows the modification targets; deletion, overwriting, raw XML, installation, and MCP registration must be confirmed separately.
4. For three or more modifications, prefer an atomic batch. After completion, perform schema, issues, and visual checks in sequence.
5. The final receipt states the execution layer used, number of modifications, output files, validation evidence, and remaining limitations.

Example:

检查 <report.docx> 的格式和结构问题，先不要修改
把 <deck.pptx> 第 3 页标题改掉，输出为 <deck-fixed.pptx>
审计 <workbook.xlsx>，确认后批量修复公式和格式
用 OfficeCLI 复验刚生成的 PPTX，并给出逐页截图

Dependencies and installation

Install this skill:

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-dev-design@soia

When you only want this one skill, you can use the npx route. Note that the skill will land in the shared source of truth ~/.agents/skills; if the plugin is also installed, the same skill will appear as two indexes and each will drift, so it is recommended to choose one of the two:

npx skills add soia-team/soia-open-dev-design-skills -g -a '*' -s soia-dev-officecli-ops -y

The core workflow requires the official officecli executable. First perform a read-only check:

python3 scripts/check_env.py

When missing, only report the official installation options and do not automatically execute remote installation scripts. You can install according to the current instructions in the OfficeCLI official repository , then use officecli --version to verify. When using a custom binary, set:

OFFICECLI_BIN=<path-to-officecli>

This skill does not require credentials or private configuration. OfficeCLI's install、mcp, plugin installation, and agent skill installation will modify the user's environment, and are only performed after the customer explicitly requests it and confirms the target.

The safety wrapper sets OFFICECLI_SKIP_UPDATE=1, to prevent a single document operation from changing the CLI version in the background. Upgrades should be performed as an independent task and verified.

Relationship with other capabilities:

• soia-dev-open-design-ops: design systems, templates, HTML visual source of truth, and high-fidelity export; not a replacement for OfficeCLI.
• Host presentations/documents/spreadsheets: responsible for the creation route specified by the host; this skill must not bypass the host's hard constraints.
• OfficeCLI: responsible for cross-host OOXML reading, precise editing, batch processing, validation, and preview.

The complete selection table is in references/tool-routing.md。

WorkBuddy is loaded as role-based experts rather than plugins,npx skills add -a '*' does not cover it; it needs to be installed separately, see docs/install/workbuddy.md。

Logs and completion receipts

完成：<检查、创建或副本修改结果>。

- execution_layer: officecli
- source: <输入路径；新建时省略>
- output: <输出路径；只读时省略>
- operations: <读取/修改/批处理数量>
- schema: clean | failed | skipped
- issues: <数量与类别>
- visual_review: passed | failed | skipped

验证：<实际运行的命令与人工检查范围>
限制：<缺少渲染器、未做 Office App 实机检查或其他残余风险>

Positioning and hard boundaries

1. The atomic layer does not make design decisions. Content structure, narrative order, brand direction, and template selection are decided by upper-layer skills or the client.
2. Default is copy-on-write. Modifying an existing file must output to a different path;scripts/officecli_safe.py in-place modification is rejected.
3. Overwriting requires explicit confirmation. When the output already exists, first show the target; only after client confirmation use --overwrite。
4. L1 → L2 → L3。 First view/get/query, then DOM set/add/..., and only lastly use raw/raw-set; do not directly modify XML because you are unfamiliar with the schema.
5. Paths must come from read results. Prefer stable @id、@name、@paraId, do not guess drift-prone positional indices.
6. A file existing does not equal completion. validate Only proves OpenXML schema; readability, formulas, layout, and visuals still need corresponding quality gates.
7. Third-party boundaries. This skill depends on Apache-2.0 OfficeCLI, but does not copy, modify, or impersonate its built-in skills.
8. "Reading" also goes through a temporary copy. The upstream will repair XML encoding or dangling relationships in place when opening certain abnormal files; to protect the source file, by default query through officecli_inspect.py .

Standard workflow

1. Environment check

python3 scripts/check_env.py
python3 scripts/check_env.py --json

Minimum recommended OfficeCLI 1.0.137, because starting from this version batch executes atomically by default. Stop write operations at lower versions; read-only checks may continue after explicitly noting that compatibility is unverified.

2. Read-only inventory

First confirm the format and target, then narrow down layer by layer on a temporary copy:

python3 scripts/officecli_inspect.py --input <file> -- view outline
python3 scripts/officecli_inspect.py --input <file> -- view stats --json
python3 scripts/officecli_inspect.py --input <file> -- view issues --json
python3 scripts/officecli_inspect.py --input <file> -- get / --depth 2 --json
python3 scripts/officecli_inspect.py --input <file> -- query '<selector>' --json
python3 scripts/officecli_inspect.py --input <file> -- validate --json

When screenshots are needed, use --artifact-output <preview.png> -- view screenshot. When attribute names, value formats, or command syntax are uncertain, first run officecli help <format> <element> --json, do not guess from memory.

3. Establish a modification plan

Record each modification: target path, read-back before modification, action, expected read-back, and risk. Write three or more modifications as batch JSON, first check all selectors and stable paths, then execute once.

Deletion, replacement, raw XML, accepting/rejecting revisions, formula rewriting, and overwrite output are high-risk actions. Before execution, show the scope and output path to the client.

4. Execute on a copy

Execute single or small DOM modifications through the safe wrapper:

python3 scripts/officecli_safe.py \
  --input <source.pptx> \
  --output <result.pptx> \
  --dry-run \
  -- set '/slide[1]/shape[@id=42]' --prop text='New title'

After client confirmation, remove --dry-run. If the output already exists and the client explicitly agrees to overwrite, add --overwrite。

Create a new file:

python3 scripts/officecli_safe.py --output <result.docx> --dry-run -- create
python3 scripts/officecli_safe.py --output <result.docx> -- create

The wrapper only allows document modification verbs, not install、mcp、plugins、watch or arbitrary shell; use subprocess argv invocation, not through the shell. For detailed recipes see references/command-recipes.md。

5. Read-back and quality gates

After execution, at least check:

1. The target path read-back matches expectations.
2. officecli validate <output> --json No schema error.
3. officecli view <output> issues --json Key issues have been handled or explained.
4. Layout-sensitive tasks generate HTML/screenshots and manually review all relevant pages.
5. Before handing off to non-OfficeCLI programs or clients, run close, ensuring resident content has been flushed to disk.

For the complete thresholds of each format, see references/quality-gates.md。

MCP and resident

• For multiple rounds of modification, you can first officecli open <file>, and at the end officecli close <file>; before reading across tools, you must flush/close.
• MCP and CLI share the same command semantics. MCP tool parameters are a single command string or argv; do not invent structured format/type parameters.
• Registering or unregistering MCP modifies other applications' configurations; first read the current state and obtain explicit confirmation.
• watch is a local preview service, using loopback only by default; do not expose it to network interfaces.

Resources

• Tool selection and Open Design boundaries:references/tool-routing.md
• Common commands and batch mode:references/command-recipes.md
• DOCX/XLSX/PPTX acceptance:references/quality-gates.md

Acceptance

• Static:check_env.py can accurately report missing, outdated versions, and available status.
• Security: The wrapper rejects in-place modification, unknown verbs, overwriting without confirmation, and non-Office extensions.
• Forward: Use the real OfficeCLI to create and modify DOCX/XLSX/PPTX fixtures; all three file types pass schema validation.
• Visual: When layout is involved, render all affected pages and inspect them manually; do not use validate in place of visual acceptance.