orchestrating-cursor-cloud-agent

Files (1)

• SKILL.md

SKILL.md (first lines)

# Cursor Cloud Agent オーケストレーション

あなた自身がオーケストレーターとしてCursor Cloud Agentにタスクを委託し、監視・レビュー・フォローアップを行います。コーディング作業はCursorに任せ、あなたは判断・監視・指示に特化します。

## 使用タイミング

<trigger>

以下の場合にこのスキルを発動してください：

- ユーザーが「Cursorに投げて」「Cursor Cloud Agentに任せて」「Cursorに委託して」と言及したとき
- ユーザーがCursor Cloud Agentを使ったタスク実行を依頼したとき

</trigger>

## 前提条件

- 環境変数 `CURSOR_CLOUD_AGENT_API_KEY` が設定されていること（Basic認証に使用）
- `gh` CLI がインストール・認証済みであること（Pull Request状態確認に使用）
- Linear MCP server (`https://mcp.linear.app/mcp`) が設定・認証済みであること
- `cursor-agent-cli` がインストール済みであること（`go install github.com/syou6162/cursor-agent-cli@latest`）

## 実行手順

<procedure>

### 1. タスク内容の確認

ユーザーと会話して、Cursor Cloud Agentに委託するタスク内容を固めます。

確認すべき項目：

- ターゲットリポジトリのURL
- 開始ブランチ（未指定の場合は `main`）
- タスクの概要・目的
- 関連するLinear issue（あれば）
- 特別な制約や注意点

### 2. エージェント作成

Cursor Cloud Agent APIでエージェントを作成します。

```bash
cursor-agent-cli create \
  -repo "https://github.com/<owner>/<repo>" \
  -branch "<開始ブランチ>" \
  -prompt "<タスク指示>"
```

プロンプトは `-prompt` フラグに加えて、標準入力（パイプ）からも渡せます。優先順位は `-prompt` フラグ > 標準入力 > エラーです。標準入力はパイプ経由の場合のみ有効で、TTY（対話端末）では読み取りません。

```bash
echo "<タスク指示>" | cursor-agent-cli create \
  -repo "https://github.com/<owner>/<repo>" \
  -branch "<開始ブランチ>"
```

長いプロンプトやシェルのクオート問題を避けたい場合は、ファイルに書いてパイプで渡すと安全です。

```bash
cat prompt.txt | cursor-agent-cli create \
  -repo "https://github.com/<owner>/<repo>" \
  -branch "<開始ブランチ>"
```

<important>

- `cursor-agent-cli create` は自動的に `autoCreatePR: true` を送信する。後から変更できないため、CLI の挙動に依存してよい。
- レスポンスの `agent.url` を必ずユーザーに提示すること。API経由で作成したエージェントはWeb UIの一覧に表示されないことがあるため、直リンクが必要。

</important>

<important>

**プロンプトに必ず含めるCI確認指示:**

Cursorへのタスクプロンプト（`create` / `run`）には、以下の指示を**毎回末尾に**含めること:

> コード変更を push した後、必ず `gh pr checks <PR番号> --repo <owner>/<repo>` で CI の状態を確認してください。
> 失敗しているチェックがあれば、`gh run view <run_id> --repo <owner>/<repo> --log-failed` でログを確認し、原因を特定して修正してください。
> すべてのチェックが pass するまで修正・push・確認を繰り返してください。

Cursor は自動では CI を確認しない（専用ツールや MCP を持たない）。`gh` CLI は認証済みで利用可能だが、プロンプトで明示的に指示しない限り自発的にはチェックしない。

</important>

レスポンスから `agent.id` と `run.id` を抽出し、後続のステップで使用します。

### 3. リアルタイムストリーム監視（推奨）

SSEストリームに接続し、エージェントの実行をリアルタイムで監視します。

```bash
cursor-agent-cli stream <agent_id> <run_id>
```

- NDJSON（1行1JSON）でイベントを出力
- 主要イベント: `status`（状態変更）、`assistant`（テキストデルタ）、`thinking`（思考デルタ）、`tool_call`（ファイル読み書き・シェル実行等）、`result`（最終結果）、`done`（終了）
- **ポーリングよりも推奨**: Cursorが「今何をやっているか」が分かるため、オーケストレーターとしての判断精度が上がる
- 終了コード: `done` イベント受信時は 0、`error` イベント受信時は 2
- `result` イベントに最終返答テキスト・`git` 情報（Pull Request URL含む）が含まれる

### 3b. ステータスポーリング（フォールバック）

ストリームが使えない場合のフォールバック手段です。

```bash
cursor-agent-cli status <agent_id> <run_id> --watch
```

- `cursor-agent-cli status` はデフォルトで15秒間隔でポーリングする。`--watch` を付けると、終了状態に到達するまで自動的にポーリングを続行する。
- **終了条件**: `status` が `FINISHED` / `ERROR` / `CANCELLED` / `EXPIRED` のいずれか
- `FINISHED` 時に `result` フィールドに最終返答テキスト、`git.branches[0].prUrl` にPull RequestのURLが含まれる

### 3c. 実行のキャンセル

以下の場合に、実行中のrunをキャンセルします。

- Cursorが応答しなくなった場合

From syou6162/agent-skills, MIT.

More from syou6162/agent-skills