| name | tech-blog-writing |
| description | Guides writing and editing technical blog posts for recca0120.github.io (Hugo + Stack theme, bilingual zh-hant-tw + en). Covers article structure, SEO, frontmatter conventions, cover image generation, internal links via Hugo ref shortcode, plain blockquote callouts (for cross-post compatibility), and humanized zh-hant writing style. Use this skill whenever the user writes, drafts, edits, translates, or restructures any article on this blog — even if they don't explicitly say "blog post" (e.g. "幫我整理成一篇", "改寫這段", "翻成英文版"). |
| allowed-tools | Read, Write, Edit, Bash, Glob, Grep |
技術部落格文章撰寫規範
專案資訊
- Hugo + Stack 主題
- 設定檔：
config/_default/ 下多個 .toml
- 文章放在：
content/post/{slug}/index.md
- 部署：push 到
main 分支自動透過 GitHub Actions 部署到 GitHub Pages
- 網址：https://recca0120.github.io/
寫作流程
- 建立目錄
content/post/{slug}/
- 確認主題和目標讀者
- 想一個帶數字或具體成果的標題
- 寫 3 句 hook 開場（痛點、數據或場景）
- 列出起承轉合的大綱
- 寫繁體中文初稿
index.md（目標 1,500-2,500 字）
- 套用 humanizer-zh 規則檢查 AI 痕跡
- 確認程式碼可讀、有註解、可複製貼上
- 加入相關文章的內部連結（格式：
[標題]({{< ref "/post/slug" >}})，詳見 writing-style.md）
- 需要補充、提示、警告時用純 blockquote（
> text）— 避免 GitHub Alerts，因為 dev.to / Hashnode 不渲染
- 文章末尾加入
## 參考資源 區塊（見參考資源規範）
- 確認 frontmatter 格式正確（見
frontmatter-reference.md）
- 寫英文版
index.en.md（完整翻譯，不是摘要）
- 用 Cloudflare Workers AI 產封面圖（見
cover-image.md）
hugo --gc --minify 確認建置無錯誤- commit 並 push 到
main
文章結構：起承轉合
每篇文章必須有明確的敘事線。
- 起（問題或情境）：直接描述狀況或目標，貼出錯誤訊息或觸發條件
- 承（原因分析）：用一兩句話說明技術原因，貼關鍵原始碼片段
- 轉（解決方案）：具體可操作的步驟，程式碼有語言標記和中文註解
- 合（補充）：注意事項或替代方案。有就寫，沒有就不寫
- 參考資源：文章末尾固定加上參考資源區塊（見下方規範）
參考資源區塊
每篇文章結尾必須加上 ## 參考資源 區塊，列出撰寫本文時參考的官方文件、GitHub repo、相關教學等。
格式：
## 參考資源
- [官方文件標題](https://official-docs-url)
- [GitHub Repo 名稱](https://github.com/org/repo)
- [相關文章或教學標題](https://url)
規則：
- 只列實際參考過的資源，不堆砌無關連結
- 連結文字用描述性短句，不要只寫 "官方文件" 或 URL
- 優先列：官方文件 > GitHub repo > 官方部落格文章 > 其他教學
- 英文版對應到相同資源的英文版頁面（如果有）
- 最少 2 個，最多 8 個
關鍵原則
語氣（詳見 writing-style.md）
- 用「我」描述自己的經驗，直接陳述事實
- 句子長短交錯，技術名詞保留英文，中英文之間空一格
- 禁止 AI 填充詞、聊天機器人語氣、三段式列舉
SEO
- H1 包含主要關鍵字，前 100 字內出現主要關鍵字
description 150-160 字元，包含關鍵字和價值主張- 相關文章之間互相連結，用描述性錨點文字
套件介紹規範
- 首次提到套件名稱時，附上官方連結（GitHub repo、npm、Packagist 等）
- 文章介紹或深度使用的套件，加入
tags
- 介紹套件的文章必須包含安裝指令
Agent 使用規則
- 批次處理文章時，使用 Agent tool 並行處理
- Agent 的 model 參數至少指定
sonnet，不要用 haiku
- 每個 agent 處理 10-15 篇為一批
參考文件
frontmatter-reference.md — Frontmatter 格式、title/description/slug 規則、分類與標籤cover-image.md — Cloudflare Workers AI 封面圖產生writing-style.md — 語氣規範、高參與度寫作原則
