microsoft-word 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.5 (2026-10-13)
+Discovery only; no script or skill behaviour changed.
+- npm description rewritten as a one-sentence answer (what, which app, which agents), under 250 characters; more npm keywords and GitHub topics.
+- README opens with a TL;DR and adds "What it does" and an FAQ.
+
 ## 0.1.4 (2026-10-13)
 Fixes from the 12 round-4 reviews (`feedback/word/round4/SYNTHESIS.md`, mean 9.47). 0.1.3 is on npm from the release branch; this version carries the merged main.
 

package/README.md

@@ -1,5 +1,7 @@
 # Microsoft Word agent skill
 
+**TL;DR:** `microsoft-word` is a free, MIT-licensed agent skill that teaches AI agents (Claude Code, Cursor, Codex, Gemini CLI and other agents that read SKILL.md skills) to read, create, edit, convert, update and safely share Word documents, with tested guidance for python-docx, docx.js, docxtpl, pandoc, mammoth, LibreOffice, Office.js, VBA and Microsoft Graph. Install: `npx skills add skillsaas/microsoft-word` or `npm install microsoft-word`.
+
 `microsoft-word` is an [Agent Skills](https://agentskills.io/specification) skill that teaches AI coding agents (Claude Code, Cursor, Codex, Gemini CLI and others) to read, create, edit, convert, update and safely share Word documents without breaking them.
 
 Unofficial. Microsoft and Word are trademarks of Microsoft Corporation. This project is not affiliated with or endorsed by Microsoft.
@@ -34,6 +36,32 @@ python scripts/docx_refresh.py --check            # JSON: what can run here
 ```
 `skill.json` holds the name, version, description and entry file for catalogs.
 
+## What it does
+- `inspect_docx.py`: read-only inventory with `--json`, risks (macros, remote templates, DDE and INCLUDE fields, altChunk, OLE), residue and `--check-clean`.
+- `docx_replace.py`: find and replace across split runs, optional tracked replacement, `--expect` count, never overwrites.
+- `docx_sanitize.py`: accept changes, remove comments, hidden text and metadata, then re-inspect and fail on anything left.
+- `docx_refresh.py`: rebuild the TOC and fields or export PDF with LibreOffice in bubblewrap (or unshare), no network, macros off (Linux).
+- References for OOXML, extraction losses, conversion fidelity, Office.js, VBA, COM and Graph; Python 3.9+ with lxml.
+
+## FAQ
+**What is the microsoft-word skill?**
+An Agent Skills package (a `SKILL.md` plus references and Python scripts) that tells an AI agent how to work with Word documents correctly. It is unofficial and not affiliated with Microsoft.
+
+**Why does find and replace in a .docx miss text?**
+Word often splits one word across several runs with different formatting. `docx_replace.py` replaces across runs and reports how many matches it changed.
+
+**How do I update a table of contents without Word?**
+`docx_refresh.py` updates fields and the TOC with LibreOffice in a sandbox on Linux; it refuses on macOS and Windows, and `references/fallbacks.md` lists the options there.
+
+**How do I remove tracked changes, comments and metadata before sharing?**
+`docx_sanitize.py` makes a cleaned copy and re-inspects it; `inspect_docx.py --check-clean` shows what remains.
+
+**How do I install it in Claude Code?**
+`npx skills add skillsaas/microsoft-word`, or copy `SKILL.md`, `references/` and `scripts/` to `~/.claude/skills/microsoft-word/`, then `pip install -r scripts/requirements.txt`.
+
+**Is it safe with documents from strangers?**
+The inspector only reads and lists macros, remote templates and fields. LibreOffice runs only in isolation with no network and macros off.
+
 ## Contents
 | Path | Purpose |
 | :--- | :--- |
@@ -60,7 +88,7 @@ Tests: `python tests/smoke_test.py` (repo only, not in the npm package). It buil
 - Formats: docx, docm, dotx, dotm, doc, rtf, odt; PDF output.
 - Tested with python-docx 1.2.0, mammoth 1.11.0, pandoc 3.9, LibreOffice 25.2.3.2, lxml 6.1, Python 3.13 (docx 9.10.0 and docxtpl 0.20.2 in 0.1.0).
 - Catalog of all skillsaas skills (planned, not yet published): https://github.com/skillsaas/index
-- GitHub topics to set when the repo is created: `agent-skill`, `agent-skills`, `skill-md`, `claude-code-skill`, `microsoft-word`, `docx`, `python-docx`.
+- GitHub topics: `agent-skill`, `agent-skills`, `skill-md`, `claude-code-skill`, `microsoft-word`, `docx`, `python-docx` and more.
 - `docx_refresh.py --sandboxed` is for operators only; agents never pass it (`references/security.md`).
 
 ## License

package/SKILL.md

@@ -4,7 +4,7 @@ description: "Use when reading, creating, editing, converting, comparing, redact
 license: MIT
 compatibility: "Python 3.9+ with lxml for the bundled scripts (any OS). docx_refresh.py is Linux only: it needs LibreOffice and isolation, bubblewrap (bwrap, preferred, hides the user's files) or unshare (network only). Word itself is optional. pandoc, mammoth and python-docx are optional readers."
 metadata:
-  version: "0.1.4"
+  version: "0.1.5"
   updated: "2026-10-13"
   last-verified: "2026-10-13 (python-docx 1.2.0, mammoth 1.11.0, pandoc 3.9, LibreOffice 25.2.3.2, bubblewrap, lxml 6.1, Python 3.13 on Linux; docx 9.10.0 npm and docxtpl 0.20.2 in 0.1.0); automation check 2026-10-13: Office.js type-checked against @types/office-js 1.0.611, Graph checked against msgraph-metadata 15780e9 of 2026-10-06, VBA checked against docs only, no live Word or tenant runs; Word UI steps (references/word-ui.md) documented only"
   risk: "medium"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "microsoft-word",
-  "version": "0.1.4",
-  "description": "Agent skill (SKILL.md) for Microsoft Word: read, create, edit, convert, update fields and safely share .docx/.docm/.doc/.rtf with python-docx, docx.js, docxtpl, pandoc, mammoth, LibreOffice, Office.js, VBA and Microsoft Graph. Includes hardened inspect, split-run replace, sanitize and sandboxed field-refresh scripts (Python).",
+  "version": "0.1.5",
+  "description": "Agent skill for Microsoft Word for Claude Code, Cursor, Codex and other SKILL.md agents: inspect, edit, replace text across runs, sanitize and convert .docx/.doc/.rtf; python-docx, pandoc, Office.js and VBA guides.",
   "license": "MIT",
   "author": "Ali Tanveer",
   "repository": {
@@ -45,7 +45,15 @@
     "table-of-contents",
     "mammoth",
     "sharepoint",
-    "bubblewrap"
+    "bubblewrap",
+    "word-skill",
+    "docx-skill",
+    "ai-agent-skill",
+    "claude-skills",
+    "codex-skills",
+    "find-and-replace",
+    "docx-sanitize",
+    "document-redaction"
   ],
   "files": [
     "SKILL.md",

package/skill.json

@@ -1,6 +1,6 @@
 {
   "name": "microsoft-word",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Use when reading, creating, editing, converting, comparing, redacting or automating Microsoft Word documents (.docx, .docm, .dotx, .dotm, .doc, .rtf): find and replace that misses text split across runs, python-docx, docx.js (docx npm), docxtpl, mammoth or pandoc output that loses text or formatting, stale TOC or REF fields, tracked changes and comments, headers and footers, numbering, content controls, mail merge, LibreOffice headless PDF export, Office.js, VBA or Microsoft Graph automation, SharePoint or OneDrive files, and safe handling of untrusted documents (macros, remote templates, DDE fields, hidden text and metadata before sharing). Not needed for plain text or Markdown files that never become a Word document.",
   "entry": "SKILL.md",
   "skill_md_url": "https://raw.githubusercontent.com/skillsaas/microsoft-word/main/SKILL.md",