soia-dev-officecli-ops

soia-dev-officecli-ops

Encapsulates OfficeCLI as an Office file atomic operation layer reusable by higher-level skills. It handles environment checks, structural reading, stable targeting, copy-then-modify, OpenXML validation, and preview evidence; it does not decide content, narrative, branding, or visual direction for higher-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; render HTML/screenshots when necessary	Issue list, element paths, previews, and repair suggestions
Precisely modify existing Office files	Prioritize locating by stable ID/name, execute on a copy set/add/remove/move/swap	New file, modification receipt, validation results
Perform multiple modifications at once	Organize 3 or more operations into an atomic batch	Success/failure steps; on failure, do not deliver a half-finished product
Create basic Office files	Create DOCX/XLSX/PPTX structures and progressively add content	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 instructions

How customers use it

1. Provide a .docx、.xlsx or .pptx path, and specify whether to inspect, create, or modify.
2. When modifying an existing file, also specify the output path; by default, generate a copy and do not overwrite the source file 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, prioritize using an atomic batch. After completion, perform schema, issues, and visual checks in sequence.
5. The final receipt specifies 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:

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

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

python3 scripts/check_env.py

If missing, only report the official installation options; do not automatically execute remote installation scripts. You may install according to the current instructions of the OfficeCLI official repository and then verify with officecli --version 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 environment; execute only after the customer explicitly requests it and confirms the target.

The security wrapper sets OFFICECLI_SKIP_UPDATE=1to 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 host 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。

Logging and completion receipt

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

- 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 the upper-layer skill or the client.
2. Default copy-on-write. Modifying an existing file must output to a different path;scripts/officecli_safe.py in-place modification is refused.
3. Overwriting must be explicitly confirmed. When the output already exists, first show the target, and only use it after the client confirms --overwrite。
4. L1 → L2 → L3。 First view/get/query, then DOM set/add/..., and only finally use raw/raw-set; do not directly modify XML because you are unfamiliar with the schema.
5. The path must come from the read result. Prefer stable @id、@name、@paraId, and do not guess at drift-prone position indexes.
6. A file existing does not mean it is complete. validate It only proves OpenXML schema; readability, formulas, layout, and visuals still require the corresponding quality gates.
7. Third-party boundaries. This skill depends on the Apache-2.0 OfficeCLI, but does not copy, modify, or impersonate its built-in skills.
8. "Reading" also goes through a temporary copy. When opening certain abnormal files, the upstream will repair XML encoding or dangling relationships in place; 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 when the version is lower; read-only checks may continue after clearly 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 a screenshot is needed, use --artifact-output <preview.png> -- view screenshot. When the attribute name, value format, or command syntax is uncertain, first run officecli help <format> <element> --json, and do not guess from memory.

3. Establish a modification plan

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

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

4. Execute on the copy

Execute single or small numbers of 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, then 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, and does not allow install、mcp、plugins、watch or arbitrary shell; use subprocess argv invocation, without going through the shell. For detailed recipes, see references/command-recipes.md。

5. Read-back and quality gate

After execution, at least check:

1. The target path read-back is consistent with expectations.
2. officecli validate <output> --json No schema error.
3. officecli view <output> issues --json The key issues have been handled or explained.
4. For layout-sensitive tasks, generate HTML/screenshots and manually review all relevant pages.
5. Before handing off to a non-OfficeCLI program or the client, run close, to ensure resident content has been written to disk.

See the complete thresholds for each format in references/quality-gates.md。

MCP and resident

• For multiple rounds of modification, first officecli open <file>, and at the end officecli close <file>; before cross-tool reading, 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 the configuration of other applications; first read the current state and obtain explicit confirmation.
• watch is a local preview service, using only loopback 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, version-too-low, 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 as a substitute for visual acceptance.