# KingClawArmy - Agent / Skills Review（dev） > 日期：2026-04-11 > 審查對象：`origin/dev` > 初次審查 commit：`ced587c` > 第二輪追蹤 commit：`ee06e6d` > 第三輪追蹤 commit：`e894446` > 用途：檢查 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 統計數量已更新 目前只剩 1 個實質問題，且已不是前一輪那種會直接造成 import warning 的 blocker。 我實際用： ```bash paperclipai company import --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 內容多半是摘要版，和文檔宣稱的「完整上游技能」仍有落差 第二次追蹤審查時，我重新跑了： ```bash paperclipai company import --dry-run --json ``` 第二輪追蹤後，結果已變成： 1. `warnings: []` 2. `errors: []` 3. 指定 skills 的 slug 都能正確進 manifest 4. Edge skills 已各自保有獨立 slug 第三輪追蹤後，我再次驗證： ```bash paperclipai company import --dry-run --json ``` 結果依然是： 1. `warnings: []` 2. `errors: []` 但 `envInputs` / `manifest.envInputs` 仍然都是空陣列，表示環境輸入需求尚未真正進到 portability manifest。 --- ## 2. 目前剩餘問題 ### P7. `.paperclip.yaml` 的 `envInputs` 寫了，但 importer 目前沒有真正吃到 **現況** 第二輪追蹤後，`.paperclip.yaml` 已把 env input 從頂層移到 project extension 下，但目前寫法仍然沒有被 importer 吃到。 目前結構是： ```yaml projects: daily-quant-pipeline: inputs: env: - name: FRED_API_KEY - name: FUGLE_API_KEY - name: ALPACA_API_KEY - name: ALPACA_API_SECRET - name: FMP_API_KEY ``` 參考： - [.paperclip.yaml](/Users/chirs/workspace/KingClawArmy_dev_review/.paperclip.yaml:83) 但我重新跑 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，但它預期的是「以 env var 名稱為 key 的 object」，不是目前這種 list 寫法。 **建議修法** 1. 依 Paperclip 目前支援的結構，把 `inputs.env` 改成 object 形式 2. 若暫時不改，也要在文檔明確標示「目前僅作 repo 端提示，尚未進 manifest」 **建議採用：** 優先採第 1 種，讓 import manifest 真的能帶出 env inputs。 建議格式： ```yaml projects: daily-quant-pipeline: inputs: env: FRED_API_KEY: description: FRED API key kind: secret requirement: optional FUGLE_API_KEY: description: Fugle MarketData API key kind: secret requirement: optional ``` --- --- ## 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` 參考： - [agents/bullish-researcher/AGENTS.md](/Users/chirs/workspace/KingClawArmy_dev_review/agents/bullish-researcher/AGENTS.md:5) - [agents/data-analyst/AGENTS.md](/Users/chirs/workspace/KingClawArmy_dev_review/agents/data-analyst/AGENTS.md:5) - [agents/ceo/AGENTS.md](/Users/chirs/workspace/KingClawArmy_dev_review/agents/ceo/AGENTS.md:5) - [agents/quant-strategist/AGENTS.md](/Users/chirs/workspace/KingClawArmy_dev_review/agents/quant-strategist/AGENTS.md:5) 但 dry-run 匯入結果顯示，Paperclip 最後辨識出的 slug 其實是： - `canslim` - `vcp` - `pead` - `dcf` - `druckenmiller` - `excel` - `edge` 參考： - [skills/canslim-screener/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/canslim-screener/SKILL.md:1) - [skills/dcf-model/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/dcf-model/SKILL.md:1) - [skills/edge-candidate-agent/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/edge-candidate-agent/SKILL.md:1) - [skills/stanley-druckenmiller-investment/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/stanley-druckenmiller-investment/SKILL.md:1) - [skills/xlsx/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/xlsx/SKILL.md:1) **影響** 這不是單純命名風格問題，而是實際綁定會失效。 我實測匯入 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` 參考： - [skills/edge-candidate-agent/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/edge-candidate-agent/SKILL.md:1) **影響** 這代表 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 科學計算環境 - 檔案系統持久化能力 參考： - [mcp-plan.md](/Users/chirs/workspace/KingClawArmy_dev_review/docs/mcp-plan.md:1) - [canslim-screener/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/canslim-screener/SKILL.md:32) - [earnings-calendar/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/earnings-calendar/SKILL.md:23) - [portfolio-manager/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/portfolio-manager/SKILL.md:1) - [trader-memory-core/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/trader-memory-core/SKILL.md:33) 但 package 端目前只有： - agent adapter - project metadata - routine schedule 參考： - [.paperclip.yaml](/Users/chirs/workspace/KingClawArmy_dev_review/.paperclip.yaml:1) **追蹤結果：** 已修正。 目前已新增： 1. `.mcp.json` 2. runtime 狀態文件 3. `Alpaca` / `FMP` 等 MCP 依賴聲明 4. `optional / needs-key / local-runtime` 的狀態說明 目前剩下的唯一缺口已收斂為 P7：`envInputs` 寫法尚未真正進 manifest。 **影響** 這代表目前是「skill 文檔存在」，不是「skill 能實際跑起來」。 換句話說，package 已有知識層，但 runtime 還沒封裝完成。 --- ### 已修正 P4. 目前 vendored 的 skill 內容偏摘要版，和文檔宣稱的完整度不一致 **現況** 文檔目前宣稱： - 來自真實開源 repo - 很多技能是數百到上千行 - 詳細內容可用 `references/` 或 `scripts/` 補齊 參考： - [agent-skill-mapping.md](/Users/chirs/workspace/KingClawArmy_dev_review/docs/agent-skill-mapping.md:5) - [skills-inventory.md](/Users/chirs/workspace/KingClawArmy_dev_review/docs/skills-inventory.md:18) - [skills-inventory.md](/Users/chirs/workspace/KingClawArmy_dev_review/docs/skills-inventory.md:46) 但實際 repo 目前： 1. 幾乎所有 `SKILL.md` 都小於 80 行 2. 多數只有摘要說明與大綱 3. `skills/` 下沒有 `reference/`、`references/`、`scripts/` 舉例： - [market-news-analyst/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/market-news-analyst/SKILL.md:1) - [canslim-screener/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/canslim-screener/SKILL.md:1) - [portfolio-manager/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/portfolio-manager/SKILL.md:1) - [xlsx/SKILL.md](/Users/chirs/workspace/KingClawArmy_dev_review/skills/xlsx/SKILL.md:1) **影響** 這會造成兩個問題： 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 個分配` 參考： - [agent-skill-mapping.md](/Users/chirs/workspace/KingClawArmy_dev_review/docs/agent-skill-mapping.md:26) 但我實際掃 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/...` 參考： - [mcp-plan.md](/Users/chirs/workspace/KingClawArmy_dev_review/docs/mcp-plan.md:141) - [mcp-plan.md](/Users/chirs/workspace/KingClawArmy_dev_review/docs/mcp-plan.md:152) - [mcp-plan.md](/Users/chirs/workspace/KingClawArmy_dev_review/docs/mcp-plan.md:195) **影響** 即使這裡只是示意值，這種寫法仍然不適合進 canonical package docs，原因是： 1. 容易讓人誤把示意值當真 key 2. 絕對路徑沒有可攜性 3. 違反 base package 應避免機器相依值的原則 **追蹤結果：** 已修正。API key 已改為 placeholder，機器相依絕對路徑也已抽換。 --- ## 4. 建議補齊清單 請另一個 agent 依序補： 1. 把 `.paperclip.yaml` 的 `inputs.env` 改成 Paperclip importer 會讀到的 object 結構 2. 重新跑 `paperclipai company import --dry-run --json` 3. 確認 `envInputs` / `manifest.envInputs` 不再為空 4. 若後續要提升為完整 vendored skills，再補 `references/` / `scripts/` --- ## 5. 修完後的驗收標準 至少要確認： 1. `paperclipai company import --dry-run --json` 仍保持 `warnings: []`、`errors: []` 2. `manifest.envInputs` 不再為空，且能反映 package 真正需要的環境輸入 3. `mcp-plan.md`、`.mcp.json`、`.paperclip.yaml` 三者口徑一致 --- ## 6. 一句話結論 這版 `dev` 的 agent / skills 已經把最重要的 Paperclip 綁定與 runtime 規劃問題修乾淨了；目前只剩 `envInputs` 的 YAML 結構尚未符合 importer 預期，屬於最後一個 portability 細節問題。