跳轉到

Codeer Agent Skill

Codeer Agent Skill 讓 Codex 或 Claude Code 可以參與完整 Agent 生命週期：從 KB 檔案開始規劃、建立 behavior cases、診斷失敗測試、分析 production history，並在套用修改前先提出下一輪迭代計畫。

Skill 不是要取代 Codeer Web UI。它的用途是讓 AI coding assistant 能在你的資料、測試、歷史紀錄和迭代流程中，用可審核、可驗證的方式協作。

CLI 和 Skill 各自負責什麼

元件 負責的事情
Codeer CLI 安裝在本機的 codeer 指令工具。它負責登入 Codeer、連接 API，並執行 Agent、KB、behavior cases、history、evaluation 等操作。
Codeer Agent Skill 安裝到 Codex 或 Claude Code 的工作說明。它讓 assistant 知道 Codeer Agent 生命週期怎麼走、什麼時候要先討論、什麼時候要先讓你看修改內容。

Skill 可以幫你做什麼

安裝後，Codex 或 Claude Code 可以協助你：

  1. 從 KB 或檔案開始規劃並建立 Agent v0

    • 從文件、FAQ、SOP、產品資料或資料夾開始。
    • 先討論 Agent 範圍、知識邊界與初版設計，再建立內容。

  2. 產生 behavior cases

    • 依照目標使用情境建立 behavior categories、test cases 與評分 standards。
    • 讓品質討論有具體依據，而不是只看單次對話。

  3. 診斷失敗 cases

    • 失敗不一定代表 prompt 錯。
    • 問題也可能在 KB、Agent instructions、retrieval、standard 或 rubric。

  4. 分析 production history 與 negative feedback

    • 從真實對話和負評中找出重複模式、測試缺口與高風險情境。

  5. 準備下一輪迭代

    • 先整理證據、提出最小有效修改、預覽會改哪些內容，再由你確認是否套用或發布。

步驟 1：建立 Admin API key

請使用目標 workspace 的 Admin API key。Skill 會透過 CLI 做 Agent、KB、behavior cases、history 和 evaluation 相關工作，因此初次設定建議使用 Admin 權限的 workspace key。

  1. 打開目標 workspace。
  2. 從左側選單進入 API Keys。
  3. 點選 Issue New Key。

工作空間中的 API Keys 畫面

建立 key 時：

  • 使用容易辨識的名稱，例如 Codex 或 Claude Code。
  • Access level 選 Admin。
  • 立即複製完整 API key。

Issue New API Key 視窗

完整 API key 只會顯示一次

請在建立當下立刻複製並妥善保存。不要貼進聊天、prompt、Git repo、專案 .env 檔案，或 .claude/settings.json。

步驟 2：安裝 Codeer CLI

Skill 會透過本機 codeer CLI 操作 Codeer API。建議使用 pipx 安裝，讓 CLI 跟專案 Python 環境分開，比較容易維護。

pipx install codeer-cli

確認指令可用：

codeer --help

如果你還沒有 pipx：

python -m pip install --user pipx
python -m pipx ensurepath

重開 terminal 後再執行：

pipx install codeer-cli

維護更新：

pipx upgrade codeer-cli
codeer check

專案 Python 安裝只建議作為 fallback

python -m pip install codeer-cli 可以作為 fallback，但 pipx 比較不容易受到專案套件版本影響。

步驟 3：設定本機 CLI profile

Profile 會把 API key 存在使用者層級的 Codeer CLI config，不需要放進 Codex 或 Claude Code 的設定檔。

work 只是範例名稱；你可以換成 codeer、prod、client-a 或其他容易辨識的名稱。

codeer profile add work
codeer profile use work

如果你改用別的名稱，兩個指令都要使用同一個 profile 名稱。

檢查 CLI 與 credential 是否可用：

codeer check
codeer agent list

這只能確認 CLI 和 API credential 正常，還不是 Skill 驗證。

若專案只有一個預設 Agent，可以選填：

export CODEER_AGENT_ID=<agent-id>

不要把 CODEER_API_KEY 放進 .claude/settings.json、專案 .env 檔案、聊天訊息或 Git commit。

步驟 4：安裝 Codeer Agent Skill

請從公開 GitHub repository 安裝 codeer-agent 資料夾。安裝時使用資料夾 URL，不要使用 repository root：

https://github.com/codeer-ai/codeer-skills/tree/main/codeer-agent

Claude Code 請把 Skill 安裝到個人 skills 資料夾：

git clone https://github.com/codeer-ai/codeer-skills.git
mkdir -p ~/.claude/skills
cp -R codeer-skills/codeer-agent ~/.claude/skills/codeer-agent

Codex：

$skill-installer install https://github.com/codeer-ai/codeer-skills/tree/main/codeer-agent

如果安裝後沒有看到 Skill，請重新啟動 Codex 或 Claude Code。

步驟 5：驗證 Skill 是否被載入

在 Codex 或 Claude Code 中問：

Please confirm whether the Codeer Agent Skill is loaded. Explain how you can help me plan an Agent from KB/files, create behavior cases, analyze production history, and show me proposed changes before applying them.

理想回答應該提到：

  • Agent lifecycle
  • Behavior Cases
  • Production History
  • 建立、更新或發布 Codeer 資源前會先向你確認

Skill 會怎麼和你協作

Skill 的角色是把 Agent 改善流程拆成可以討論、可以確認的步驟：

  • 先了解你的目標、資料來源和目前 Agent 狀態，再提出適合的工作順序。
  • 需要建立或調整 Agent、KB、behavior cases、rubrics 時，會先說明它準備做什麼。
  • 真正套用修改前，會先讓你預覽會改哪些內容，或用修改前後差異的方式讓你確認。
  • 發布新版 Agent 前，會先確認測試結果、失敗分析和修改內容都已經被看過。

CLI 常見問題快速排除

問題 檢查方式
codeer: command not found 執行 pipx ensurepath，重開 terminal 後再試一次。
codeer check 顯示 401 或 403 API key 可能過期、被撤銷或權限不足。請重新建立 Admin workspace key 並更新 profile。
看到錯的 workspace 目前 profile 可能使用了另一個 workspace 的 API key。改用正確 profile 後再執行 codeer check。
找不到 Agent 確認 CODEER_AGENT_ID 是否屬於同一個 workspace；不確定時先 unset 後執行 codeer agent list。

安裝完成後，下一步做什麼

把你的狀態對到下面的情境，直接用這些方向請 Codex 或 Claude Code 開始工作：

  • 如果你還沒有 Agent：這些是我的 KB / 文件資料夾，請先跟我討論適合建立什麼 Agent v0、需要哪些資料、有哪些風險邊界。
  • 如果你有 Agent，但還沒有 behavior cases：請根據這個 Agent 的任務，設計 behavior categories、cases 和 rubrics，先讓我審核再套用。
  • 如果你有 behavior cases，但有些沒有通過：請分析失敗原因，判斷應該修 KB、Agent instructions、retrieval，還是 standard / rubric，並先讓我看會改哪些內容。
  • 如果你的 Agent 已經上線：請分析 Production History / Negative Feedback，找出常見失敗模式、缺少的測試覆蓋，以及下一輪應優先處理的問題。
  • 如果你準備開始下一輪迭代：請根據目前問題、測試結果與歷史紀錄，提出下一版修改計畫；先讓我看證據與會改哪些內容，再決定是否套用或發布。

相關指南