Loop-Skill

KO | EN

gitlite — search

#javascript #react #ai #typescript #go #golang #rust #linux #nodejs #macos #awesome #kubernetes #ios #mcp

(★ 23)

No description available.

Loop-Skill Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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 不只是「回答」，而是「交一份可檢查、可追蹤、可修改、可交接的成果」。

![Loop Skill architecture](https://raw.githubusercontent.com/Toolsai/Loop-Skill/main/docs/images/loop-skill-architecture.png)

## 安裝

使用 Skills CLI 安裝：

```bash
npx skills add Toolsai/Loop-Skill
```

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

```bash
npx skills add <owner/repo>
```

如果你想手動下載：

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

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

官方文件：

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

## 快速開始

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

```text
使用 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 把這個流程變成：

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

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

![Loop Skill workflow](https://raw.githubusercontent.com/Toolsai/Loop-Skill/main/docs/images/loop-skill-workflow.png)

## 背後原理

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/`：

```text
.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

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

問題：

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

### 使用 Loop Skill

```text
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：

```bash
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
```

開始下一輪：

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

驗證：

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

產生 evidence report：

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

產生 reader report 和 dashboard：

```bash
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

```text
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。

Loop-Skill

Loop-Skill Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Loop-Skill

Loop-Skill Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README