chris/KingClawArmy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0cbaed38c37ffb258545066c645ba1d3b1150373
KingClawArmy/docs/paperclip_agent_skills_review_2026-04-11.md
Chris 3451ce7d77 docs: update agent skills follow-up review
2026-04-11 05:25:48 +08:00

14 KiB
Raw Blame History

KingClawArmy - Agent / Skills Review（dev）

日期：2026-04-11 審查對象：origin/dev 初次審查 commit：ced587c 追蹤審查 commit：ee06e6d 用途：檢查 Agent 配置、Skills 完整度、Paperclip 匯入相容性與 runtime 落地程度

1. 結論摘要

這一輪 dev branch 在 agent / skills 層有明顯進展：

  1. agent 的 skills: 配置已大幅補齊
  2. skills/ 目錄已有大量實體 SKILL.md
  3. docs/agent-skill-mapping.md、docs/skills-inventory.md、docs/mcp-plan.md 已開始補文檔

第二輪追蹤後，前一輪的 P1-P6 已大多修正完成：

  1. skills 已補明確 slug
  2. AGENTS.md 的 skill 參照已與匯入後 slug 對齊
  3. Edge skills 不再撞成單一 edge
  4. .mcp.json 已進 repo
  5. 文檔已改口徑為摘要版 skills
  6. skills 統計數量已更新

目前仍有 2 個「完整度」層級的缺口，但已不是前一輪那種會直接造成 import warning 的 blocker。

我實際用：

paperclipai company import <repo> --dry-run --json

第一次審查時，package 雖然仍可匯入，但有一批與 skills 相關的 warning，顯示：

  1. 多個 AGENTS.md 內填的 skill slug 匯入後對不到實際 skill
  2. 有 4 個不同的 Edge skill 在 manifest 中撞成同一個 slug
  3. skills 依賴的 MCP / API / runtime 還停在規劃，沒有跟 package 一起落地
  4. skills 內容多半是摘要版，和文檔宣稱的「完整上游技能」仍有落差

第二次追蹤審查時，我重新跑了：

paperclipai company import <repo> --dry-run --json

結果已變成：

  1. warnings: []
  2. errors: []
  3. 指定 skills 的 slug 都能正確進 manifest
  4. Edge skills 已各自保有獨立 slug

2. 目前剩餘問題

P7. .paperclip.yaml 的 envInputs 寫了，但 importer 目前沒有真正吃到

現況

.paperclip.yaml 現在新增了：

envInputs:
  - name: FRED_API_KEY
  - name: FUGLE_API_KEY

參考：

但我重新跑 dry-run import 後，manifest.envInputs 仍然是空陣列。

影響

這代表 package 雖然開始描述 runtime input，但在目前 Paperclip portability 規則下，這兩筆需求還沒有真的進到 import manifest。

也就是說：

  1. repo 端已寫
  2. importer preview 端尚未保留

若目標是讓 package 自帶可攜的環境需求聲明，這一塊還沒真正落地。

推測原因

我對照 Paperclip portability 實作後，目前 importer 會從 agent / project extension 的 inputs.env 讀 env inputs，而不是讀 .paperclip.yaml 頂層的 envInputs。

建議修法

  1. 依 Paperclip 目前支援的結構，把 env input 移到 agent / project extension 的 inputs.env
  2. 或保留現在的寫法，但補一份文件明確說明「目前僅作 repo 端提示，尚未進 manifest」

建議採用：

優先採第 1 種，讓 import manifest 真的能帶出 env inputs。

P8. Runtime 配置已有進展，但還沒有完整覆蓋 active skills 的所有依賴

現況

現在 repo 已新增：

  • .mcp.json
  • .paperclip.yaml 內的基本 env input 提示

參考：

這代表 runtime 不再是純規劃，這點是好的。

但目前仍有幾類依賴沒有完整落地：

  1. portfolio-manager 需要的 Alpaca MCP
  2. earnings-calendar / economic-calendar-fetcher 這類技能實際依賴的 FMP 路徑
  3. pair-trade-screener 需要的本地 Python/scipy/statsmodels
  4. trader-memory-core 需要的持久化檔案系統策略

參考：

影響

目前 package 已可被正確匯入，但若標準是：

skills 不只存在，而且 active agents 可在既定 runtime 下直接使用

那這一層還差最後一段 ops / runtime 補完。

建議修法

至少補這些資訊中的一種：

  1. .mcp.json 補齊缺少的 server
  2. README / docs 補明哪些 skill 是 optional / unavailable / future
  3. 對需要本地依賴的 skill 補 runtime prerequisites
  4. 對暫時無法啟用的 skill，在 mapping 文件裡加狀態標記

3. 已修正問題（追蹤確認）

已修正 P1. Agent 綁定的 skill slug 與匯入後的實際 slug 不一致

現況

多個 agent 使用了如下 skill 參照：

  • canslim-screener
  • vcp-screener
  • pead-screener
  • dcf-model
  • stanley-druckenmiller-investment
  • edge-candidate-agent
  • edge-hint-extractor
  • edge-concept-synthesizer
  • edge-pipeline-orchestrator
  • xlsx

參考：

但 dry-run 匯入結果顯示，Paperclip 最後辨識出的 slug 其實是：

  • canslim
  • vcp
  • pead
  • dcf
  • druckenmiller
  • excel
  • edge

參考：

影響

這不是單純命名風格問題，而是實際綁定會失效。

我實測匯入 warning 包含：

  1. Agent bullish-researcher references skill canslim-screener, but that skill is not present in the package.
  2. Agent bullish-researcher references skill vcp-screener, but that skill is not present in the package.
  3. Agent bullish-researcher references skill pead-screener, but that skill is not present in the package.
  4. Agent bullish-researcher references skill dcf-model, but that skill is not present in the package.
  5. Agent ceo references skill stanley-druckenmiller-investment, but that skill is not present in the package.
  6. Agent data-analyst references skill edge-candidate-agent, but that skill is not present in the package.
  7. Agent data-analyst references skill xlsx, but that skill is not present in the package.
  8. Agent data-analyst references skill edge-hint-extractor, but that skill is not present in the package.
  9. Agent data-analyst references skill edge-concept-synthesizer, but that skill is not present in the package.
  10. Agent quant-strategist references skill edge-pipeline-orchestrator, but that skill is not present in the package.
  11. Agent quant-strategist references skill stanley-druckenmiller-investment, but that skill is not present in the package.

建議修法

二選一，選一種統一：

  1. 在每個 SKILL.md frontmatter 明確補 slug，並與 AGENTS.md 內使用的 shortname 對齊
  2. 反過來把所有 AGENTS.md 內的 skill entry 改成 importer 實際產出的 slug

追蹤結果：

已修正。SKILL.md 已補 slug frontmatter，重新 dry-run import 後，相關 warnings 已清空。

已修正 P2. 四個 Edge skill 匯入後撞成同一個 edge slug

現況

以下四個 skill 路徑在 dry-run manifest 內全部被辨識成 edge：

  1. skills/edge-candidate-agent/SKILL.md
  2. skills/edge-concept-synthesizer/SKILL.md
  3. skills/edge-hint-extractor/SKILL.md
  4. skills/edge-pipeline-orchestrator/SKILL.md

參考：

影響

這代表 importer 沒有把這四個技能視為四個可獨立引用的 shortname。

後果是：

  1. agent 端無法穩定引用特定 Edge skill
  2. package 內的 skill graph 會失真
  3. 後續 export/import round-trip 可能再度發生重名覆蓋或綁錯

追蹤結果：

已修正。這四個 Edge skill 都已有獨立 slug，重新 dry-run import 後不再撞名。

已部分修正 P3. Skills 依賴的 runtime / MCP / env 還沒跟 package 一起落地

現況

許多 skill 已經在內容中假設有：

  • yfinance
  • fred
  • casual-market
  • tradingview
  • FMP API
  • Alpaca MCP
  • Python 科學計算環境
  • 檔案系統持久化能力

參考：

但 package 端目前只有：

  • agent adapter
  • project metadata
  • routine schedule

參考：

追蹤結果：

已部分修正。

目前已新增：

  1. .mcp.json
  2. .paperclip.yaml 中的 env input 提示

但 env input 尚未真正進 manifest，而且 runtime 仍未完整覆蓋所有 active skills，剩餘缺口已移到 P7 / P8。

影響

這代表目前是「skill 文檔存在」，不是「skill 能實際跑起來」。

換句話說，package 已有知識層，但 runtime 還沒封裝完成。

已修正 P4. 目前 vendored 的 skill 內容偏摘要版，和文檔宣稱的完整度不一致

現況

文檔目前宣稱：

  • 來自真實開源 repo
  • 很多技能是數百到上千行
  • 詳細內容可用 references/ 或 scripts/ 補齊

參考：

但實際 repo 目前：

  1. 幾乎所有 SKILL.md 都小於 80 行
  2. 多數只有摘要說明與大綱
  3. skills/ 下沒有 reference/、references/、scripts/

舉例：

影響

這會造成兩個問題：

  1. package 使用者以為 skills 已完整 vendored，其實只有摘要版
  2. agent 的能力敘述看起來很強，但可重現工作流不足

追蹤結果：

已修正文件口徑。agent-skill-mapping.md 現在已明確說明目前是 Summary Reference 版 skills，而不是完整 vendored 版。

已修正 P5. 文檔統計已經與實際 repo 不一致

現況

目前 docs/agent-skill-mapping.md 寫：

  • 62 個 SKILL.md
  • 71 個分配

參考：

但我實際掃 repo：

  1. skills/ 目錄共 53 個 skill
  2. agents 的 skills: 總分配數是 72

影響

這會誤導下一位 agent，以為：

  1. repo 少了 9 個 skill
  2. 或某些配置還沒同步

追蹤結果：

已修正。文件中的 skill 數量與分配數量已更新為當前 repo 狀態。

已修正 P6. mcp-plan.md 仍含敏感或機器相依資訊，不適合留在 package docs

現況

這份文件目前包含：

  1. 明文 FRED_API_KEY
  2. 機器相依的絕對路徑 /home/chris/workspace/...

參考：

影響

即使這裡只是示意值，這種寫法仍然不適合進 canonical package docs，原因是：

  1. 容易讓人誤把示意值當真 key
  2. 絕對路徑沒有可攜性
  3. 違反 base package 應避免機器相依值的原則

追蹤結果：

已修正。API key 已改為 placeholder，機器相依絕對路徑也已抽換。

4. 建議補齊清單

請另一個 agent 依序補：

  1. 讓 env inputs 依 Paperclip 目前支援的結構真正進 manifest
  2. 補齊 active skills 的 runtime 覆蓋缺口
  3. 為尚未可直接啟用的 skill 補 optional / unavailable / future 狀態說明
  4. 若後續要提升為完整 vendored skills，再補 references/ / scripts/

5. 修完後的驗收標準

至少要確認：

  1. paperclipai company import --dry-run --json 仍保持 warnings: []、errors: []
  2. manifest.envInputs 不再為空，且能反映 package 真正需要的環境輸入
  3. active skills 的 runtime 依賴都有對應配置或明確狀態標記
  4. mcp-plan.md、.mcp.json、.paperclip.yaml 三者口徑一致

6. 一句話結論

這版 dev 的 agent / skills 已經把最重要的 Paperclip skill 綁定問題修乾淨了；目前剩下的是 envInputs 尚未真正進 manifest，以及 runtime 覆蓋還沒百分之百收尾，屬於完整度問題，不是基本相容性問題。

Reference in New Issue View Git Blame Copy Permalink