chris/KingClawArmy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ee06e6de6b554708a38a53026d5d35e8f659b6da
KingClawArmy/docs/paperclip_agent_skills_review_2026-04-11.md
Chris cf556a8c63 docs: add agent skills review
2026-04-11 05:15:19 +08:00

12 KiB
Raw Blame History

KingClawArmy - Agent / Skills Review（dev）

日期：2026-04-11 審查對象：origin/dev 審查 commit：ced587c 用途：檢查 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 已開始補文檔

但目前還不能視為已完整收斂。

我實際用：

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 內容多半是摘要版，和文檔宣稱的「完整上游技能」仍有落差

2. 主要問題

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

建議採用：

優先採第 1 種。
也就是讓 skill package 自己明確宣告穩定 slug，避免 agent 端追著 importer 的正規化規則跑。

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 可能再度發生重名覆蓋或綁錯

建議修法

這四個 SKILL.md 必須都補明確、互不衝突的 slug：

  1. edge-candidate-agent
  2. edge-concept-synthesizer
  3. edge-hint-extractor
  4. edge-pipeline-orchestrator

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 的 envInputs
  3. secrets / key requirement 聲明
  4. 哪些 skill 是 hard requirement、哪些是 optional fallback

影響

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

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

建議修法

至少補以下四類資料：

  1. repo 內的 .mcp.json 草稿或正式版
  2. .paperclip.yaml 的 envInputs
  3. 每個需要外部能力的 skill，其 required MCP / API / local runtime
  4. required / optional / unavailable 的分級標記

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

現況

文檔目前宣稱：

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

參考：

但實際 repo 目前：

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

舉例：

影響

這會造成兩個問題：

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

建議修法

這裡要明確選邊站：

  1. 若目標是「摘要版 skills library」：就把文檔改成摘要版，不要再寫成完整上游技能
  2. 若目標是「完整 vendored skills」：就補 references/、scripts/、關鍵工作流、必要範本

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. 或某些配置還沒同步

建議修法

把統計欄位改成和 repo 實際狀態一致。
如果之後還會持續增減，建議不要手寫固定數字，改成描述型文字。

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

現況

這份文件目前包含：

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

參考：

影響

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

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

建議修法

  1. 所有 key 一律改成 placeholder
  2. 所有絕對路徑一律改成相對或說明性文字
  3. 若要保留實作版本，請移到不納入 package 的私有部署文件

3. 建議補齊清單

請另一個 agent 依序補：

  1. 為所有 SKILL.md 補明確 slug frontmatter
  2. 先修正這批被 warning 的 skill slug 對齊問題：
    • canslim-screener
    • vcp-screener
    • pead-screener
    • dcf-model
    • stanley-druckenmiller-investment
    • xlsx
    • edge-candidate-agent
    • edge-hint-extractor
    • edge-concept-synthesizer
    • edge-pipeline-orchestrator
  3. 確保四個 Edge skill 匯入後不再全部變成 edge
  4. 補 .mcp.json 或等價 runtime 配置檔
  5. 在 .paperclip.yaml 補 envInputs / runtime requirements
  6. 為每個依賴外部服務的 skill 標記：
    • required MCP
    • required API key
    • required local runtime
    • optional fallback
  7. 決定 skills 是「摘要版」還是「完整 vendored 版」，並把文檔口徑統一
  8. 修正文檔中的技能數量與配置數量
  9. 清掉 mcp-plan.md 的敏感與機器相依資訊

4. 修完後的驗收標準

至少要確認：

  1. paperclipai company import --dry-run --json 不再出現 skill missing warnings
  2. 所有 agent 在 manifest 中引用到的 skill slug 都能對上
  3. 四個 Edge skill 在 manifest 中是四個獨立 skill，不再撞名
  4. docs/agent-skill-mapping.md 的統計與 repo 實際一致
  5. package 有明確的 runtime / MCP / env requirement 定義
  6. mcp-plan.md 不再含敏感值與絕對路徑

5. 一句話結論

這版 dev 的 agent / skills 架構方向正確，但目前主要缺口不在「數量」，而在「skill slug 尚未穩定、runtime 尚未落地、內容完整度與文檔口徑尚未對齊」，還需要再補一輪才能稱得上完整。

Reference in New Issue View Git Blame Copy Permalink