report-writing

report-writing — 寫報告技能(Claude Code / Codex Skill)

產製正式技術報告 docx 交付物的可重用方法庫,特別針對繁體中文政府/招標交付。涵蓋從理解規格到驗證交付的全流程、內容策略、繁中排版、docx 生產工具鏈(真方程式、可點交互參照、目錄頁碼、圖)與驗證品保。

萃取自一個繁中液態火箭引擎模擬器的 TASA 期中報告專案(docx 多版迭代)的實戰經驗,寫成通用方法。

安裝

這是一個可同時給 Claude Code 與 Codex 使用的 Skill,下列兩種方式擇一(請勿並用,避免同一技能重複載入)。

方式一:git clone(Claude Code / Codex 皆適用)

複製到對應使用者層級的 skills 目錄即可:

# Claude Code: macOS / Linux
git clone <this-repo> ~/.claude/skills/report-writing

# Claude Code: Windows (Git Bash)
git clone <this-repo> "$HOME/.claude/skills/report-writing"

# Codex: macOS / Linux
git clone <this-repo> ~/.codex/skills/report-writing

# Codex: Windows (PowerShell)
git clone <this-repo> "$HOME\.codex\skills\report-writing"

放好後,Claude Code / Codex 在你「寫報告 / 產製 docx 交付」時會依 SKILL.md 的 description 自動載入。agents/openai.yaml 提供 Codex/OpenAI 端的技能列表顯示資訊。

方式二:Claude Code plugin(一鍵安裝與更新)

Claude Code 使用者可把本 repo 當成 marketplace 安裝,日後用一行指令更新:

/plugin marketplace add LostSunset/report-writing-skill
/plugin install report-writing

• 技能名固定為 report-writing(由 SKILL.md frontmatter 的 name 決定,不隨安裝目錄漂移),觸發時機與方式一相同;SKILL.md 留在 repo 根、references/ 相對路徑不變,與方式一完全同一份內容。
• 更新:/plugin update report-writing;移除:/plugin uninstall report-writing。
• 此法會把整個 repo 複製進 Claude Code 的 plugin 快取(~/.claude/plugins/cache)。三支 linter 若要實跑,比照下方 Quick Start 在快取內該 plugin 目錄 uv sync;想自行掌控目錄與環境者用方式一。
• 僅限 Claude Code;Codex 端請用方式一。

產出即審(自動複審 hook)

以方式二安裝為 plugin 後,本技能會註冊一個 PostToolUse hook(hooks/hooks.json → scripts/hooks/lint_gate.py):Claude Code 每次以 Write/Edit/MultiEdit 寫出 .md/.txt/.docx/.pptx/.html/.htm/.pdf 文檔後,便自動以三支離線 linter 複審剛落地的檔案,不靠模型自覺。

• 有明確問題(error)→ 以 PostToolUse 的回饋機制(exit 2 + stderr)逐條把「found→suggest」與修正指引回饋給模型;改完存檔會自動再複審。回饋文末含逃生門提示與「確為必要用語可保留並說明豁免」一句,避免誤報時模型反覆改不掉而卡住。
• 僅風格提醒(warn)→ 非阻斷單行提示。注意:PostToolUse 於 exit 0 時,stdout 只寫入 transcript 供人查看、不注入模型,故 warn 不會驅動模型自動修正;唯有 error(exit 2 的 stderr)才會回饋模型修正。乾淨 → 安靜放行。
• 安靜放行(不審)的情形:非文檔副檔名、檔案大於 2MB、或 file_path 落在技能安裝目錄之內、或本技能 repo 的任何工作副本之內(以指紋兩檔 references/data/zh-ai-tells.json + corpus/lint_terms.py 偵測;後者避免使用者一邊用 plugin、一邊編輯另一份 clone 的 references/*.md 時把字典示例詞全標成問題)。
• 支援格式:.md、.txt、.docx、.pptx、.html/.htm、.pdf(其餘副檔名一律安靜放行,不誤審程式碼/設定檔)。
• 啟動成本(誠實揭露):hook 的 matcher 無法按副檔名過濾,故每次 Write/Edit/MultiEdit 都會啟動一個程序(約 0.2–0.5 秒 uv run 暖啟動開銷);非文檔副檔名在程序內立即放行(不跑 linter),文檔則另加純 linter 內核約 0.35 秒。在意此開銷者用逃生門停用。
• 首次生效需 plugin 快取目錄已 uv sync(見下方 Quick Start;hooks.json 以 uv run --directory "${CLAUDE_PLUGIN_ROOT}" 呼叫,故一次 uv sync 於該快取內即可);相依未裝、字典缺失或任何內部錯誤時 hook 一律友善放行,絕不因自身問題卡住寫檔。
• 逃生門:設環境變數 REPORT_WRITING_LINT_GATE=off 即整個停用本 hook(放行所有寫檔),遠低於保守的 60 秒 timeout。

git clone(方式一)用戶:手動啟用

方式一是純技能安裝,Claude Code 不會自動掛 hook。要同樣獲得「產出即審」,在你的 ~/.claude/settings.json(或專案層 .claude/settings.json)的 hooks.PostToolUse 加一筆——把 command 兩處路徑改成你的技能絕對路徑即可(方式一 clone 到 ~/.claude/skills/report-writing;plugin 端靠 ${CLAUDE_PLUGIN_ROOT} 自動代入,方式一無此變數故需寫死絕對路徑):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "uv run --directory \"/Users/you/.claude/skills/report-writing\" python \"/Users/you/.claude/skills/report-writing/scripts/hooks/lint_gate.py\"",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Windows 用戶請用下列完整可複製 JSON 區塊(勿只抄 command 一行——路徑內的反斜線在 JSON 字串內須跳脫成 \\、內嵌雙引號須跳脫成 \",漏跳脫會壞掉 settings.json):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "uv run --directory \"C:\\Users\\you\\.claude\\skills\\report-writing\" python \"C:\\Users\\you\\.claude\\skills\\report-writing\\scripts\\hooks\\lint_gate.py\"",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

先在該技能目錄 uv sync 建好 .venv(見下方 Quick Start),存檔後新開的 Claude Code 工作階段即生效;逃生門與放行規則同上。

Quick Start(clone 之後)

技能本體是純文件,不裝也能被載入使用;下面三支 linter 需要 Python 環境。用 uv 建 .venv(Python 3.12,不新增 runtime 依賴):

cd ~/.claude/skills/report-writing   # 進技能目錄(下記 <技能根目錄>)
uv sync                              # 依 uv.lock 建 .venv

uv sync 會安裝穩定 console script；以下兩種呼叫等價，後續範例優先使用較短的前者：

uv run --directory <技能根目錄> report-project --version
uv run --directory <技能根目錄> python -m report_project --version

若要獨立散布 CLI，可用 uv build 產生 wheel；wheel 內含驗證模組與四份內建 policy 資料，不依賴原 clone 路徑。report-project status --config /abs/path/report.toml 可先看各階段是否設定、必要 artifact 是否存在，但它是只讀盤點，不等於 QA 通過。