docs: add agent skills review

2026-04-11 05:15:19 +08:00
parent ced587c2f2
commit cf556a8c63
2 changed files with 359 additions and 1 deletions
--- a/docs/INDEX.md
+++ b/docs/INDEX.md
@@ -15,7 +15,7 @@ agents/*/AGENTS.md              ← 11 個 agent 定義
 teams/*/TEAM.md                 ← 2 個 team（management, quant-research）
 projects/*/PROJECT.md           ← 2 個 project
 projects/*/tasks/*/TASK.md      ← 4 個 recurring tasks
-skills/*/SKILL.md               ← 2 個 skills
+skills/*/SKILL.md               ← 53 個 skills
 ```

 ---
@@ -31,6 +31,7 @@ skills/*/SKILL.md               ← 2 個 skills
 | [schemas.md](schemas.md) | 所有 Agent 輸出的 JSON Schema 定義（含信心指數、恐慌指數、進出場建議） |
 | [paperclip_org_plans.md](paperclip_org_plans.md) | 組織規劃方案（A/B/C）、推薦方案、修改範圍與 review 驗收標準 |
 | [paperclip_dev_review_2026-04-11.md](paperclip_dev_review_2026-04-11.md) | 第一版 Paperclip package 審查備忘錄，列出必修問題、建議修法與驗收標準 |
+| [paperclip_agent_skills_review_2026-04-11.md](paperclip_agent_skills_review_2026-04-11.md) | Agent / Skills 完整度審查，聚焦 skill slug、runtime 依賴、內容完整度與文檔一致性 |

 ---

--- a/docs/paperclip_agent_skills_review_2026-04-11.md
+++ b/docs/paperclip_agent_skills_review_2026-04-11.md
@@ -0,0 +1,357 @@
+# 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` 已開始補文檔
+
+但目前還**不能視為已完整收斂**。
+
+我實際用：
+
+```bash
+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`
+
+參考：
+
+- [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
+
+**建議採用：**
+
+優先採第 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`
+
+參考：
+
+- [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 可能再度發生重名覆蓋或綁錯
+
+**建議修法**
+
+這四個 `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 科學計算環境
+- 檔案系統持久化能力
+
+參考：
+
+- [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. `.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/` 補齊
+
+參考：
+
+- [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 的能力敘述看起來很強，但可重現工作流不足
+
+**建議修法**
+
+這裡要明確選邊站：
+
+1. 若目標是「摘要版 skills library」：就把文檔改成摘要版，不要再寫成完整上游技能
+2. 若目標是「完整 vendored skills」：就補 `references/`、`scripts/`、關鍵工作流、必要範本
+
+---
+
+### 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. 或某些配置還沒同步
+
+**建議修法**
+
+把統計欄位改成和 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 應避免機器相依值的原則
+
+**建議修法**
+
+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 尚未落地、內容完整度與文檔口徑尚未對齊」，還需要再補一輪才能稱得上完整。