---
name: sophnet-docx
description: Create, read, edit, and manipulate Word documents (.docx files). Use when the user wants to work with Word documents, including creating reports, memos, letters, templates, or performing operations like find-and-replace, tracked changes, comments, or content extraction.
---

# DOCX creation, editing, and analysis

## MANDATORY: Task Classification — Read First

Before doing ANYTHING else, classify the user's intent into one of three categories. Then load ONLY the corresponding reference file.

| Intent | Keywords | Load this file | JS files? |
|--------|----------|---------------|-----------|
| **READ** | 读、看、查看、阅读、分析、评审、review、extract、parse | [references/read-docx.md](references/read-docx.md) | **NEVER** |
| **EDIT** | 改、修改、编辑、添加批注、加评论、accept changes、修订 | [references/edit-docx.md](references/edit-docx.md) | **NEVER** |
| **CREATE** | 创建、新建、生成、create、generate、写一个 docx | [references/create-docx.md](references/create-docx.md) | **ONLY here** |

**CRITICAL: `_tmp_docx_*.js` is ONLY for CREATE. If the task is READ or EDIT and you find yourself writing a JS file — STOP. You are in the wrong workflow.**

**DO NOT load reference files for other intents. READ only loads read-docx.md. EDIT only loads edit-docx.md. CREATE loads create-docx.md and docx-js-api.md.**

## MANDATORY: Working Directory

**EVERY command in this skill MUST be executed from THIS skill's directory.** Before running ANY command — Python, Node.js, or bash script — you MUST `cd` into this skill's directory first. Determine the absolute path of this `SKILL.md` file and use its parent directory.

```bash
SKILL_DIR="<absolute-path-to-this-skills-sophnet-docx-directory>"
cd "$SKILL_DIR"
```

**NEVER run commands from the repository root or any other directory.** If you do, `uv run` won't find `pyproject.toml`, and `python` won't have access to required packages.

## MANDATORY: Cleanup — Zero Residual Files

**CRITICAL: After every task, `$SKILL_DIR` must contain ONLY these permanent files:** `SKILL.md`, `pyproject.toml`, `uv.lock`, `package.json`, `package-lock.json`, `.npmrc`, `node_modules/`, `scripts/`, `references/`, `.venv/`. **NOTHING else.** No `.js` scripts, no `unpacked*/` directories, no `.py` scripts, no generated `.docx` files.

Three enforced rules (non-negotiable):

1. **JS scripts to `/tmp/` with PID.** Write JS to `/tmp/_tmp_docx_$$.js` (`$$` = shell PID, unique per session). Run with `cd "$SKILL_DIR" && node /tmp/_tmp_docx_$$.js && rm -f /tmp/_tmp_docx_$$.js`. The `&&` (not `;`) ensures the file is deleted ONLY on success — if node fails, the file stays for debugging. On skill startup, clean stale leftovers: `find /tmp/ -name '_tmp_docx_*.js' -mtime +1 -delete 2>/dev/null`.
2. **Unpack to `/tmp/` only.** NEVER unpack into `$SKILL_DIR`. Use `/tmp/_tmp_docx_unpacked/` and `rm -rf` it after packing.
3. **Python scripts go to `/tmp/`.** Write them to `/tmp/_tmp_*.py` and delete after execution.

## Python Runtime (uv)

**CRITICAL: All Python execution in this skill MUST use `uv run --project .` from the skill directory. NEVER use bare `python3`, `python`, or `pip install` directly — the required packages (python-docx, lxml, etc.) are ONLY available inside the uv virtual environment defined by this skill's `pyproject.toml`. Direct `python3` will fail with ModuleNotFoundError.**

First, ensure the environment is set up (run once per session):

```bash
cd "$SKILL_DIR"
bash scripts/ensure_uv_env.sh
```

Then ALL Python commands must use this prefix:

```bash
cd "$SKILL_DIR" && uv run --project . python <script-or-module>
```

## MANDATORY: Upload After Every Create/Edit

**CRITICAL: After creating or modifying a DOCX file, you MUST run `scripts/upload_file.sh --url-only` and include the URL in the final reply.** This is NOT optional. Do NOT return local file paths. READ tasks do NOT upload — just respond directly.

```bash
cd "$SKILL_DIR" && bash scripts/upload_file.sh --file <absolute-path-to-docx> --url-only
```

**Note:** The `cd "$SKILL_DIR"` prefix is MANDATORY — `scripts/upload_file.sh` is relative to the skill directory. Without it, the command fails with `No such file or directory`.

Upload command output contract:

- With `--url-only` and successful upload: output is exactly one line, the raw `https://...` URL
- With `--url-only` and upload fails (missing API key): `FILE_PATH=<absolute-path>`

Delivery rules:

- Final response for CREATE/EDIT MUST include: success → valid `https://...` URL; missing API key fallback → `FILE_PATH=<absolute-path>`
- READ tasks respond with analysis directly, no upload
- Do not include local file paths in CREATE/EDIT responses
- Keep URL output logic independent inside `sophnet-docx/scripts`. Do not call other skills' upload scripts.

## Quick Reference

| Task | Load | Key Commands |
|------|------|-------------|
| Prepare Python environment | — | `bash scripts/ensure_uv_env.sh` |
| Read/analyze content | read-docx.md | `pandoc` or `unpack` to `/tmp/` |
| Edit existing document | edit-docx.md | Unpack → edit XML → pack → upload |
| Add comment | edit-docx.md | `uv run --project . python scripts/comment.py` |
| Accept tracked changes | edit-docx.md | `uv run --project . python scripts/accept_changes.py` |
| Create new document | create-docx.md | docx-js → validate → upload |
| Validate a docx | create-docx.md | `uv run --project . python scripts/office/validate.py` |
| Upload | — | `bash scripts/upload_file.sh --file <path> --url-only` |

A .docx file is a ZIP archive containing XML files.
