Loop Skill

把 AI 回答變成可審核、可追蹤、可改進的成果。

Loop Skill 是一個 filesystem-backed AI workflow skill。它不是單純叫 AI「多試幾次」，而是把一個任務變成有規則、有輸出、有審核、有重寫計劃、有最終報告的 Loop System。

適合用在這類任務：

• 批量文案：Google Ads、SEO title、LinkedIn posts、email subject lines
• 有硬限制的輸出：字數、禁詞、分類、欄位、數量
• 研究/分析任務：每個 insight 都要有 evidence 和 source
• SOP / checklist：每一步要有 owner、action、pass signal
• 排名/篩選任務：Top 10、Top 15、淘汰原因、版本比較
• 需要交接的 AI 工作：同事、客戶、未來的自己都能看到證據鏈

一句話：Loop Skill 讓 AI 不只是「回答」，而是「交一份可檢查、可追蹤、可修改、可交接的成果」。

安裝

使用 Skills CLI 安裝：

npx skills add Toolsai/Loop-Skill

Vercel 官方 Skills 文件也使用同一種安裝格式：

npx skills add <owner/repo>

如果你想手動下載：

git clone https://github.com/Toolsai/Loop-Skill.git

然後把 repo 內的 skill 放到你使用的 agent skills 目錄。

官方文件：

• https://vercel.com/docs/agent-resources/skills

快速開始

在支援 skills 的 coding agent 中，使用類似這樣的提示：

使用 Loop Skill 幫我建立一個 Loop。

任務：生成 30 個 Google Ads 標題和 15 個描述，推廣香港 GEO Audit 服務。

限制：
- 標題不超過 30 個英文字符或 15 個中文字
- 描述不超過 90 個英文字符或 45 個中文字
- 不可使用「保證」「第一名」「100%」
- 需要分成 SME、專業服務、電商三個角度

請保留 run folder、audit、rewrite-plan、final.md、reader-report.md 和 dashboard。

完成後，你通常會得到：

• .loops/systems/<slug>/：這個任務的規則和審核標準
• .loops/runs/<run-id>/：這一次執行的輸出、審核、事件紀錄
• final.md：證據報告
• reader-report.md：人類易讀版
• interactive-dashboard.html：互動式 dashboard

為什麼需要 Loop Skill？

普通 AI 對話很快，但常見問題是：

• AI 說有 45 條，但可能數錯
• 有字數限制，但某幾條偷偷超了
• 有禁詞限制，但沒有逐條檢查
• 你不知道哪一條為什麼通過
• 你不知道哪一條要重寫
• 改一部分時，AI 可能把原本正確的部分改壞
• 結果只留在聊天紀錄裏，很難交接

Loop Skill 把這個流程變成：

Define -> Generate -> Audit -> Validate -> Rewrite -> Report

每一步都寫入檔案，不靠口頭聲稱完成。

背後原理

Loop Skill 使用的是：

Filesystem-backed Validator-Gated Loop

用人話講，就是：

1. 先把任務要求寫成明確規則
2. AI 產生結構化輸出
3. 客觀規則交給 validator 檢查
4. 主觀品質交給 judgment audit 留下理由和證據
5. 如果失敗，就生成 rewrite plan
6. 下一輪只修失敗項目
7. 通過後產生報告和 dashboard

它不是：

• 不是普通 prompt loop
• 不是只靠 AI 自評
• 不是無限背景自動運行
• 不是每次失敗都整份重寫

它重視的是：可驗證、可追蹤、可回看、可交接。

文件結構

Loop Skill 會在你的專案中建立 .loops/：

.loops/
  systems/
    <slug>/
      loop.json
      blueprint.md
      kickoff.md
      validator-notes.md

  runs/
    <timestamp>-<slug>/
      state.json
      events.jsonl
      feedback.jsonl
      iteration-1/
        generation-instructions.md
        output.json
        judgment-audit.json
        audit.json
        rewrite-plan.json
      final.md
      reader-report.md
      interactive-dashboard.html

簡單理解：

• .loops/systems/ 是規則、目標和審核標準
• .loops/runs/ 是某一次實際執行的結果和證據

同一套 system 可以跑很多次 run。

重要文件解釋

loop.json

機器可讀的核心規則檔。它定義目標、最大迭代次數、輸出格式、必填欄位、客觀檢查和 judgment criteria。

blueprint.md

人類可讀的計劃書。它解釋這個 Loop 要完成什麼、成功標準是什麼、最多跑幾輪。

state.json

目前狀態，例如：

• created
• awaiting_generation
• needs_rewrite
• needs_user_review
• passed
• stopped_max_iterations
• blocked

events.jsonl

事件流水帳。記錄 run 何時建立、iteration 何時開始、何時驗證、何時完成、何時產生報告。

output.json

AI 真正產出的內容，例如廣告文案、SOP、FAQ、研究洞察、排名結果。

judgment-audit.json

主觀品質審核。用來記錄「語氣是否合適」、「是否貼合受眾」、「是否有證據」、「淘汰理由是否具體」這類需要理解的判斷。

audit.json

正式審核結果。Validator 會合併客觀檢查和 judgment audit，判斷這一輪是否通過。

rewrite-plan.json

如果沒有通過，這裏會列出要修哪些項目、失敗原因和下一輪修改方向。

final.md

Evidence report。它證明這次 run 的狀態、審核結果、最終輸出和事件紀錄。

reader-report.md

讀者版報告。比 final.md 更適合給老闆、客戶或同事快速閱讀。

interactive-dashboard.html

互動式 dashboard。可以瀏覽 accepted output、分類、審核狀態和資料分佈。

Objective Checks vs Judgment Checks

Loop Skill 使用 hybrid audit。

Objective checks

適合用程式穩定檢查：

• item 數量
• 必填欄位
• 是否空白
• 字數限制
• 禁詞
• 指定 artifact 是否存在

Judgment checks

適合用 AI/人工理解後審核：

• 語氣是否專業
• 是否貼合 SME 受眾
• 是否有商業意圖
• 是否有證據
• 是否像人話
• 淘汰原因是否具體

這樣做的好處是：不會把所有語言理解硬塞進程式規則，也不會完全靠 AI 口頭說「看起來可以」。

Before / After

沒有 Loop Skill

User: 幫我寫 45 條廣告文案。
AI: 這是 45 條。
User: 你有沒有數錯？有沒有超字數？哪些最好？
AI: 應該沒有。

問題：

• 很難確認數量
• 很難確認限制
• 沒有審核證據
• 修改時容易整批重寫
• 沒有正式交付紀錄

使用 Loop Skill

1. 定義 45 條、字數、禁詞、分類要求
2. 生成 output.json
3. 寫入 judgment-audit.json
4. validate 產生 audit.json
5. 若失敗，rewrite-plan.json 指出要改什麼
6. 通過後產生 final.md、reader-report.md、interactive-dashboard.html

好處：

• 規則清楚
• 輸出可追蹤
• 審核有證據
• 失敗有修正計劃
• 最終有報告和 dashboard
• 可以交接、重跑、回看

使用案例

1. Google Ads 文案

• 30 個 headlines
• 15 個 descriptions
• 字數限制
• 禁詞檢查
• 分成 SME、專業服務、電商三個角度

2. Top 15 shortlist

• 審核全部 45 條
• 選出 Top 15
• 為其餘 30 條寫淘汰原因
• 保留原始 source id
• 產生 shortlist report

3. SEO title / meta description

• 每頁一組 title / description
• 不超過指定長度
• 每條包含指定主題
• 不重複

4. SOP / checklist

• 每步有 owner
• 每步有 action
• 每步有 pass signal
• 新人看完可以照做
• 不漏掉風險步驟

5. Research summary

• 每個 insight 必須有 source
• 每個 conclusion 要有 evidence
• 不寫空泛評論
• 產生 reader-friendly report

6. Compliance review

• 禁詞
• 誇張承諾
• 高風險說法
• 人工覆核點
• evidence 是否足夠

什麼時候適合用？

適合：

• 批量內容
• 有硬性限制
• 有分類配額
• 需要審核
• 需要反覆修改
• 需要交付客戶
• 需要團隊交接
• 需要保留證據

不太需要：

• 只問一個簡單問題
• 只改一句文案
• 純 brainstorming
• 不需要驗證的一次性靈感

常用命令

初始化一個 Loop：

python scripts/init_loop.py \
  --root . \
  --slug my-content-loop \
  --mode content \
  --goal "Generate a structured content set" \
  --target-count 10 \
  --structured-output \
  --required-field id \
  --required-field text \
  --max-iterations 3

開始下一輪：

python scripts/run_loop.py next .loops/runs/<run-id>

驗證：

python scripts/validate_loop.py .loops/runs/<run-id>

產生 evidence report：

python scripts/render_report.py .loops/runs/<run-id>

產生 reader report 和 dashboard：

python scripts/render_delivery.py .loops/runs/<run-id>

設計原則

1. 不只相信 AI 的回答，要有檢查
2. 不把所有主觀品質硬編碼，要用 judgment audit 留證據
3. 不每次失敗都整份重寫，要按 rewrite plan 精準修正
4. 不讓結果只留在聊天紀錄，要用 filesystem 保存完整過程
5. 不把 max iterations 當成功保證，它只是預算

Requirements

• Python 3
• 支援 skills 的 AI coding agent
• 不需要額外 Python package

Repository layout

SKILL.md
agents/openai.yaml
assets/profiles/*.json
references/*.md
scripts/*.py
docs/images/*.png

Notes

• Loop Skill 會建立 .loops/ 目錄保存任務執行證據。
• final.md 是 evidence report，不應手動覆蓋。
• reader-report.md 和 interactive-dashboard.html 是通過後的交付層。
• 如果 dashboard 生成成功，agent 應主動打開；不能打開時，至少要提供 file:// URL。