Control Word App Via Osascript

---
name: control-word-app-via-osascript
description: "Control Word app sessions, documents, selections, comments, export, and review state with osascript workflows."
category: "Integrations"
author: community
version: "1.0.0"
icon: plug
---

## When to Use

User needs Microsoft Word controlled as a live application, not treated as a `.docx` file format.
Agent handles app attach, active document state, selection-aware edits, comments, track changes, export, and clean shutdown through the official `osascript` CLI.
If the main artifact is offline DOCX creation or structural file editing, use `word-docx` instead.

## Architecture

Memory lives in `~/word/`. If `~/word/` does not exist, run `setup.md`. See `memory-template.md` for structure.

```text
~/word/
├── memory.md             # Environment facts, safe defaults, and last working control path
├── incidents.md          # Reusable failures and proven recovery steps
└── document-notes.md     # Non-sensitive notes about trusted documents, views, and export targets
```

## Quick Reference

Load only the smallest file that matches the current Word task and risk level.

| Topic | File |
|-------|------|
| Setup guide | `setup.md` |
| Memory template | `memory-template.md` |
| Interface selection | `execution-matrix.md` |
| Live control patterns | `live-control-patterns.md` |
| Destructive action guardrails | `safety-checklist.md` |
| Debug and recovery | `troubleshooting.md` |

## Requirements

- Microsoft Word installed locally.
- macOS with `osascript` available.
- Explicit confirmation before destructive document actions.

## Core Rules

### 1. Choose the app-control path by document state
- Use `osascript` for live Word document control through the app's scripting dictionary.
- Keep automation inside the live Word session instead of falling back to file-only DOCX tooling.
- Do not switch to offline document libraries when the requested job depends on the current live Word app state.

### 2. Identify the exact document and view before acting
- Confirm whether the target is the active document, a named open document, or a path to open now.
- Read the current view, selection, and review mode before making edits tied to cursor position or markup state.
- Never assume the frontmost Word window is the intended document.

### 3. Read before write, then verify the final state
- Pre-read document name, current selection, target paragraph, comment count, or export target before mutation.
- After edits, comments, accept/reject actions, or exports, re-read the affected state and report what changed.
- If Word does not reach the requested state, stop and diagnose instead of layering more edits.

### 4. Treat selection-driven actions as high-risk
- Selection-based commands can land in the wrong paragraph, story range, header, or comment balloon.
- When possible, anchor the action to a specific document object instead of only the current insertion point.
- If the selection context is ambiguous, clarify first.

### 5. Separate reversible review actions from destructive cleanup
- Adding comments, changing view, and exporting are usually reversible.
- Accept all changes, reject all changes, remove comments, close without save, and overwrite exports require explicit confirmation.
- If review state matters, preserve track changes and display settings unless the user explicitly asks to change them.

### 6. Keep provenance explicit
- State whether the target was already open or opened just for this task.
- Report what document was changed, which review mode was active, and where exports were written.
- Preserve user-owned open documents that were outside the task scope.

### 7. Recover cleanly and avoid orphaned app sessions
- If you opened Word just for this task, keep ownership clear and close only what you created.
- If you attached to an existing session, do not close unrelated documents or quit Word without explicit approval.
- On failure, record the exact blocker: protected document, modal dialog, compatibility mode, track changes mismatch, or missing permissions.

## Word Traps

- Treating a live document like a static `.docx` file -> review state, comments, fields, and view context drift apart.
- Writing relative to the current cursor without verifying selection -> text lands in the wrong story range.
- Accepting or rejecting changes globally when only one section was intended -> irreversible editorial loss.
- Exporting before fields, references, or TOC are updated -> stale output delivered as final.
- Closing an attached user session after automation -> unrelated writing work is interrupted.
- Ignoring protected view or tracked-change mode -> edits silently fail or create the wrong markup history.

## Security & Privacy

**Data that stays local:**
- Document paths, environment notes, and reusable fixes in `~/word/`.
- Document contents accessed through local Word automation.

**Data that may leave your machine:**
- Nothing by default from this skill itself.
- A document's own links, add-ins, macros, or cloud-backed autosave behavior may contact external systems.

**This skill does NOT:**
- Use Microsoft Graph, cloud document APIs, or OAuth flows.
- Disable review warnings silently.
- Accept destructive document-wide changes without explicit confirmation.
- Bypass Word protection prompts.

## Related Skills
Install with `clawhub install <slug>` if user confirms:
- `word-docx` — Offline DOCX generation and editing when Word does not need to stay open.
- `office` — Broader Office task routing across documents, spreadsheets, and presentations.
- `applescript` — macOS app automation patterns when Word dictionary work needs deeper script design.

## Feedback

- If useful: `clawhub star word`
- Stay updated: `clawhub sync`