Fword Skill

AI-powered bidirectional Word ↔ LaTeX converter. Supports multiple AI providers (Anthropic, OpenAI, Qwen, Kimi, MiniMax, DeepSeek, Zhipu). Converts Word to c...

Security Scan

The skill mostly does what it claims (docx ↔ LaTeX using Pandoc + optional LLM refinement) but there are important mismatches and persistence/installation behaviors you should understand before using it.

Purpose & Capability

The code and SKILL.md clearly require API keys for multiple LLM providers and persist the original .docx into a .fword workspace, but the registry metadata lists no required environment variables or credentials and claims 'instruction-only'. That registry metadata is inconsistent with the shipped scripts and their needs.

Instruction Scope

Runtime instructions (and the scripts) will: (a) send the document's LaTeX content to third-party LLM endpoints for refinement, (b) create a .fword/ workspace that stores a copy of the original .docx and manifest, and (c) suggest running scripts/setup.sh which can install system packages. All of these actions are within the skill's stated purpose but have side effects (network exfiltration of document contents to chosen providers, on-disk persistence of original files) that the user must accept explicitly.

Install Mechanism

No registry install spec is declared, but the skill provides scripts/setup.sh which will attempt to install Pandoc via apt/brew/pacman (using sudo where applicable) and pip3 install packages globally. That requires network access, may run privileged package manager commands, and will modify the host environment if executed — a non-trivial installation step that is not visible in the registry metadata.

Credentials

The SKILL.md and code expect provider API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, DASHSCOPE_API_KEY, MOONSHOT_API_KEY, MINIMAX_API_KEY, DEEPSEEK_API_KEY, ZHIPU_API_KEY or explicit --api-key / --base-url). These are reasonable for an LLM-assisted converter, but the registry incorrectly reports 'no required env vars'. Also, sending full document content to remote LLMs can expose sensitive data — the skill will do this unless you use --raw or a local/base-url endpoint.

Persistence & Privilege

The skill does not request elevated platform privileges nor modify other skills, but it creates a .fword/ workspace next to outputs and copies the original document there (reference.docx) and writes manifest.json. This persistent storage of original files is functional for round-tripping but may be unexpected for users handling sensitive documents.

What to consider before installing

Key things to consider before installing/using: - Registry metadata is inconsistent: the package claims no required env vars, but the code and SKILL.md expect provider API keys. Treat that as a red flag and confirm requirements before providing secrets. - Document leakage: AI refinement sends your document (LaTeX text) to the chosen provider. If your doc is sensitive, use the --raw Pandoc-only mode or point --base-url to a trusted/local LLM endpoint. - Persistent copies: the tool copies the original .docx into a .fword/ workspace (reference.docx) and writes manifest.json next to your files — delete that workspace if you don't want copies retained. - Installer behavior: scripts/setup.sh can call sudo apt/brew/pacman and runs pip3 install (global). Inspect and run it in a safe environment (container or virtualenv) rather than on a production host. - Minimize exposure: prefer ephemeral or least-privileged API keys, run installs inside a virtualenv or container, and review the scripts (already provided) yourself. If unsure, use --raw or run pandoc manually to avoid network calls. - If you want higher assurance: ask the publisher for corrected registry metadata and for a declaration of exactly which provider env vars are required; audit network hosts you plan to send data to; or run the tool only in an isolated VM/air-gapped environment.

Fword — Word ↔ LaTeX Converter

You are an AI assistant equipped with the Fword skill for bidirectional Word ↔ LaTeX conversion.

When to Activate

Activate this skill when the user:

• Wants to convert a .docx / Word file to LaTeX
• Wants to convert a .tex / LaTeX file back to Word
• Asks you to edit a Word document (convert to LaTeX first, edit, convert back)
• Mentions "fword" by name

Setup

Before first use, ensure dependencies are installed:

bash {SKILL_DIR}/scripts/setup.sh

Check if setup is needed by testing: python3 -c "import pypandoc, anthropic, openai, docx". If this fails, run setup.

Supported AI Providers

Provider	Env Variable	Default Model	Flag
Anthropic (Claude)	ANTHROPIC_API_KEY	claude-sonnet-4-20250514	-p anthropic
OpenAI	OPENAI_API_KEY	gpt-4o	-p openai
Qwen (Alibaba)	DASHSCOPE_API_KEY	qwen-plus	-p qwen
Kimi (Moonshot)	MOONSHOT_API_KEY	moonshot-v1-8k	-p kimi
MiniMax	MINIMAX_API_KEY	MiniMax-Text-01	-p minimax
DeepSeek	DEEPSEEK_API_KEY	deepseek-chat	-p deepseek
Zhipu (GLM)	ZHIPU_API_KEY	glm-4-plus	-p zhipu

Any OpenAI-compatible API can also be used via --base-url.

Commands

Word → LaTeX

cd {SKILL_DIR}/scripts && python3 convert.py /absolute/path/to/document.docx /absolute/path/to/output.tex

Options:

• -p, --provider PROVIDER — AI provider (default: anthropic)
• --model MODEL — AI model (default: provider's default)
• --api-key KEY — API key (or set provider's env var)
• --base-url URL — Custom API base URL
• --raw — Pandoc-only conversion, no AI refinement (no API key needed)
• --keep-intermediate — Save Pandoc's raw output as .raw.tex

Examples:

# Default (Anthropic Claude)
cd {SKILL_DIR}/scripts && python3 convert.py /path/to/doc.docx

# Use Qwen
cd {SKILL_DIR}/scripts && python3 convert.py /path/to/doc.docx -p qwen

# Use DeepSeek with specific model
cd {SKILL_DIR}/scripts && python3 convert.py /path/to/doc.docx -p deepseek --model deepseek-chat

# Pandoc only (no AI)
cd {SKILL_DIR}/scripts && python3 convert.py /path/to/doc.docx --raw

LaTeX → Word

cd {SKILL_DIR}/scripts && python3 back.py /absolute/path/to/document.tex /absolute/path/to/output.docx

Options:

• --reference-doc PATH — Use a specific Word template for styles (overrides workspace)

Workflow

Standard conversion

1. Run convert.py on the .docx file — this creates a .fword/ workspace and outputs .tex
2. The .fword/ workspace stores the original document as a style reference
3. Edit the LaTeX as needed
4. Run back.py to convert back — it automatically finds the workspace and recovers styles

AI-assisted editing workflow

When the user wants to edit a Word document with AI help:

1. Convert: convert.py document.docx → produces document.tex
2. Read the .tex file and make the requested edits directly in LaTeX
3. Convert back: back.py document.tex → produces document.docx with original styles

Quick reference

User wants...	Action
Convert Word to LaTeX	convert.py input.docx
Convert with Qwen	convert.py input.docx -p qwen
Convert with DeepSeek	convert.py input.docx -p deepseek
Convert without AI	convert.py input.docx --raw
Convert LaTeX to Word	back.py input.tex
Edit Word doc with AI	convert → edit .tex → back

Important Notes

• Always use absolute paths for input/output files
• Always cd {SKILL_DIR}/scripts before running scripts (they import each other)
• Set the appropriate environment variable for your chosen provider's API key
• If no API key is available, use --raw flag for Pandoc-only conversion
• The .fword/ workspace is created next to the output file
• For large documents, AI refinement processes in chunks automatically