Codeer Agent Skill

Codeer Agent Skill を使うと、Codex や Claude Code が Agent のライフサイクル全体に参加できます。KB ファイルからの計画、behavior case の作成、失敗したテストの診断、production history の分析、次の iteration の提案までを、変更適用前に確認しながら進められます。

Skill は Codeer Web UI の代替ではありません。AI coding assistant が、Codeer のデータ、テスト、履歴、iteration workflow に対して、レビュー可能で検証可能な形で協力するためのものです。

CLI と Skill の役割

Component	役割
Codeer CLI	ローカルにインストールする `codeer` command-line tool です。Codeer へのログイン、API 接続、Agent、KB、behavior case、history、evaluation の操作を行います。
Codeer Agent Skill	Codex または Claude Code にインストールする作業手順です。Agent lifecycle の進め方、先に計画を相談すべき場面、変更内容を適用前に見せるべき場面を assistant に伝えます。

Skill でできること

インストール後、Codex または Claude Code は次の作業を支援できます。

KB やファイルから Agent v0 を計画して作成する
- Documents、FAQ、SOP、product data、folder から始めます。
- Agent の scope、knowledge boundary、first version design を作成前に相談します。
Behavior cases を生成する
- 対象 scenario に合わせて behavior categories、test cases、scoring standards を作成します。
- 品質レビューを、一回限りの会話ではなく具体的な基準で進められます。
Failed cases を診断する
- Case failure は、必ずしも prompt が間違っているという意味ではありません。
- KB、Agent instructions、retrieval behavior、standard、rubric に問題がある場合もあります。
Production history と negative feedback を分析する
- 実際の conversations と bad feedback から、繰り返し出る pattern、足りない coverage、高リスク scenario を見つけます。
次の iteration を準備する
- Evidence を整理し、最小限の有効な修正を提案し、変更内容を preview してから、適用や publish の確認を取ります。

ステップ1：Admin API key を作成する

対象 workspace の Admin API key を使います。Skill は CLI 経由で Agent、KB、behavior cases、history、evaluation を操作するため、初回設定では Admin 権限の workspace key を推奨します。

対象 workspace を開きます。
左 sidebar から API Keys を開きます。
Issue New Key を選択します。

Workspace API Keys screen

Key を作成するときは:

Codex や Claude Code のような識別しやすい名前を使います。
Access level は Admin を選びます。
完全な API key をすぐにコピーします。

Issue New API Key modal

完全な API key が表示されるのは一度だけです

作成直後に安全な場所へ保存してください。Chat、prompt、Git repository、project .env file、.claude/settings.json には貼り付けないでください。

ステップ2：Codeer CLI をインストールする

Skill はローカルの codeer CLI を通じて Codeer API を操作します。Project Python environment から分離するため、pipx でのインストールを推奨します。

pipx install codeer-cli

Command が使えることを確認します。

codeer --help

まだ pipx がない場合:

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

Terminal を再起動してから実行します。

pipx install codeer-cli

更新と確認:

pipx upgrade codeer-cli
codeer check

Project Python への install は fallback として扱います

python -m pip install codeer-cli でも動く場合がありますが、pipx の方が project package versions の影響を受けにくく安全です。

ステップ3：ローカル CLI profile を設定する

Profile は API key を user-level の Codeer CLI config に保存します。Codex や Claude Code の設定ファイルに key を入れる必要はありません。

work は例の profile name です。codeer、prod、client-a など、識別しやすい名前に変えて構いません。

codeer profile add work
codeer profile use work

別の名前を使う場合は、両方の command で同じ profile name を使ってください。

CLI と credential が動くことを確認します。

codeer check
codeer agent list

これは CLI と API credential の確認です。Skill が読み込まれたことの確認ではありません。

Project に default Agent が 1 つだけある場合は、必要に応じて次を設定できます。

export CODEER_AGENT_ID=<agent-id>

CODEER_API_KEY を .claude/settings.json、project .env files、chat messages、Git commits に保存しないでください。

ステップ4：Codeer Agent Skill をインストールする

Public GitHub repository から codeer-agent folder をインストールします。Repository root ではなく、folder URL を使います。

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

Claude Code では、Skill を personal skills folder にインストールします。

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 では、Codex に Skill のインストールを依頼します。

$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 resource の作成、更新、publish 前に確認すること

Skill との協力の進め方

Skill の役割は、Agent improvement を相談可能で確認可能な steps に分けることです。

まず目標、data sources、現在の Agent state を理解し、作業順序を提案します。
Agent、KB、behavior cases、rubrics を作成または変更する前に、何をする予定か説明します。
実際に変更を適用する前に、preview または before-and-after diff を見せます。
新しい Agent version を publish する前に、test results、failure analysis、変更内容がレビュー済みか確認します。

Troubleshooting

Problem	確認すること
`codeer: command not found`	`pipx ensurepath` を実行し、terminal を再起動してもう一度試します。
`codeer check` が `401` または `403` を返す	API key が expired、revoked、または Admin access 不足の可能性があります。新しい Admin workspace key を作成し、profile を更新します。
違う workspace が表示される	Active profile が別 workspace の key を使っている可能性があります。正しい profile に切り替えてから `codeer check` を実行します。
Agent が見つからない	`CODEER_AGENT_ID` が同じ workspace に属しているか確認します。不明な場合はいったん unset して `codeer agent list` を実行します。

インストール後の次の一手

現在の状態に合わせて、次のように Codex または Claude Code に依頼できます。

まだ Agent がない場合: These are my KB files. Please discuss what Agent v0 we should create, what data it needs, and where the risk boundaries are.
Agent はあるが behavior cases がない場合: Please design behavior categories, cases, and rubrics for this Agent's job. Let me review them before applying.
Behavior cases の一部が fail している場合: Please analyze whether the issue is in the KB, Agent instructions, retrieval, standard, or rubric, and show me the proposed changes first.
Agent がすでに live の場合: Please analyze Production History and Negative Feedback to find repeated failure patterns, missing test coverage, and the highest-priority next fixes.
次の iteration を始める場合: Please propose the next version plan based on current issues, test results, and history. Show me the evidence and proposed changes before applying or publishing.