Skip to main content
Agent の定義

Agent スキル

Agent にドメインの専門知識を付与する。

Skills は Agent にドメインの専門知識を付与します。Skill は構造化された指示と手順のセットであり、Agent を特定のタスクにおいてより高性能かつ信頼性の高いものにします。
QoderWork または Qoder IDE をご利用の場合、スキルマーケットプレイスから Cloud Agents スキル をインストールすることで、ローカルの会話から直接 Cloud Agents を作成・管理できます。手動での API 呼び出しは不要です。

エンドポイント

メソッドパス説明
POST/api/v1/cloud/skillsSkill を作成（最初のバージョンも作成）
GET/api/v1/cloud/skillsSkill の一覧を取得
GET/api/v1/cloud/skills/{skill_id}Skill を取得
PUT/api/v1/cloud/skills/{skill_id}Skill を更新 ⚠️ 非推奨
DELETE/api/v1/cloud/skills/{skill_id}Skill を削除
POST/api/v1/cloud/skills/{skill_id}/versionsSkill バージョンを作成
GET/api/v1/cloud/skills/{skill_id}/versionsSkill バージョンの一覧を取得
GET/api/v1/cloud/skills/{skill_id}/versions/{version}Skill バージョンを取得
GET/api/v1/cloud/skills/{skill_id}/versions/{version}/contentSkill バージョンのコンテンツをダウンロード
DELETE/api/v1/cloud/skills/{skill_id}/versions/{version}Skill バージョンを削除

バージョンモデル

Skills は「Skill シェル + 不変のバージョンスナップショット」という 2 層モデルを使用します：
  • Skill シェル：id、display_title、source、metadata、latest_version ポインターなど、コンテンツに依存しない属性を保持します。
  • Skill バージョン：各バージョンは不変の完全なコンテンツスナップショットです。バージョン識別子は作成時刻を表すエポックマイクロ秒の文字列（例："1759178010641129"）で、サーバーが生成するためユーザーは指定できません。
  • コンテンツを更新するには、POST /skills/{skill_id}/versions で新しいバージョンを追加します。古いバージョンは変更されず、個別に取得、ダウンロード、削除できます。
  • 最新バージョンを削除すると、latest_version は次に新しいバージョンへフォールバックします。すべてのバージョンを削除すると null になります。
  • SKILL.md のフロントマターにある Skill の name は、すべてのバージョンで同一である必要があり、作成後は変更できません。
PUT /api/v1/cloud/skills/{skill_id} は非推奨です。コンテンツを更新するには、Skill バージョンを作成 を使用してください。

Skill の役割

  • ドメイン知識の注入 —— 汎用 Agent に特定領域の能力を付与する（コードレビュー、ドキュメント生成など）
  • 手順の標準化 —— Agent が一貫したステップに従い、一貫した出力を生成することを保証する
  • 再利用可能 —— 一度定義すれば、複数の Agent で共有できる

Skill のファイル構成

Skill は .zip アーカイブ（または multipart の個別ファイルツリー）としてアップロードします。トップレベルディレクトリは 1 つだけにし、その名前を SKILL.md の name と一致させる必要があります： 
my-skill/
├── SKILL.md          # Required: Skill definition
├── templates/        # Optional: template files
│   └── report.md
└── examples/         # Optional: example files
    └── sample.json
SKILL.md はコアファイルで、YAML フロントマター + Markdown 形式で記述します： 
---
name: my-skill
description: Perform structured code reviews and produce improvement suggestions
---

# Code Review

## Steps
1. Analyze the structure and architecture of the code.
2. Check for common issues (security, performance, maintainability).
3. Output a structured review report.

## Pitfalls
- Don't fixate on formatting — prioritize logic errors.
- Provide concrete fixes rather than vague critiques.

Skill の作成

POST https://api.qoder.com/api/v1/cloud/skills
Content-Type: multipart/form-data

curl の例

# Package the skill directory (keep the top-level directory)
zip -r my-skill.zip my-skill/

# Upload
curl -X POST https://api.qoder.com/api/v1/cloud/skills \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "files=@my-skill.zip"
レスポンス： 
{
  "id": "skill_019e5d133c057536872f745e0b6dbd5d",
  "type": "skill",
  "display_title": "my-skill",
  "source": "custom",
  "latest_version": "1759178010641129",
  "created_at": "2026-05-01T10:00:00.123456Z",
  "updated_at": "2026-05-01T10:00:00.123456Z"
}
latest_version は作成時刻を表すエポックマイクロ秒の文字列としてサーバーが生成します。SKILL.md フロントマターの version 値（例：1.0.0）は情報表示用であり、サーバー側のバージョンではありません。

Agent への関連付け

Agent の skills フィールドを更新するには POST を使用します。各関連付け要素では version を省略できます。省略するか "latest" を指定すると、常に最新バージョンを使用します。数値タイムスタンプを指定すると、そのバージョンに固定されます（保存時に存在を検証し、不明なバージョンは 400 を返します）。 
curl -X POST https://api.qoder.com/api/v1/cloud/agents/agent_abc123 \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1,
    "skills": [
      {"type": "custom", "skill_id": "skill_019e5d133c057536872f745e0b6dbd5d"},
      {"type": "custom", "skill_id": "skill_019e5cdc7a9278ba933d4c328096bac5", "version": "1759178010641129"}
    ]
  }'

バージョン管理

既存の Skill に新しいバージョンを追加します： 
curl -X POST https://api.qoder.com/api/v1/cloud/skills/skill_019e5d133c057536872f745e0b6dbd5d/versions \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "files=@my-skill-v2.zip"
バージョンを固定していない関連付けは常に最新バージョンを使用し、数値バージョンに固定した関連付けはそのスナップショットを使い続けます。

Skill の取得

curl https://api.qoder.com/api/v1/cloud/skills/skill_019e5d133c057536872f745e0b6dbd5d \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

Skill の一覧取得

curl https://api.qoder.com/api/v1/cloud/skills \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"
レスポンス： 
{
  "data": [
    {
      "id": "skill_019e5d133c057536872f745e0b6dbd5d",
      "type": "skill",
      "display_title": "code-review",
      "source": "custom",
      "latest_version": "1759178010641129",
      "created_at": "2026-05-01T10:00:00.123456Z",
      "updated_at": "2026-05-01T10:00:00.123456Z"
    },
    {
      "id": "skill_019e5cdc7a9278ba933d4c328096bac5",
      "type": "skill",
      "display_title": "doc-generator",
      "source": "custom",
      "latest_version": "1759264410332875",
      "created_at": "2026-04-20T08:30:00.482910Z",
      "updated_at": "2026-04-25T09:15:00.104276Z"
    }
  ],
  "next_page": null,
  "has_more": false
}

Skill 作成のヒント

  1. トリガーを明確にする —— この Skill がいつ使用されるべきかが明確になるよう description を記述する
  2. ステップを具体的にする —— 曖昧なガイダンスではなく、具体的なアクションを記述する
  3. 落とし穴を記録する —— Agent がよくある間違いを避けられるようにする
  4. 検証方法を提供する —— タスクが完了したことを確認する方法を Agent に伝える

よくある質問

Q：Skill と Agent の system プロンプトの違いは何ですか？ A：system はすべてのタスクに適用される汎用的な指示です。Skill はオンデマンドの専門モジュールで、Agent が直面しているタスクに応じて起動します。 Q：1 つの Agent はいくつの Skill を参照できますか？ A：ハードリミットはありませんが、予測可能な動作を保つために 10 個以内に抑えてください。 Q：Skills 機能はいつ GA になりますか？ A：本機能は M2 段階にあります。早期アクセスをご希望の場合はお問い合わせください。今後のリリースで全面展開予定です。 Q：zip にサイズ制限はありますか？ A：アーカイブは 50 MB 以下で、展開後のコンテンツも 50 MB 以下である必要があります。

次のステップ

Agent ツール

Agent に組み込み・MCP・カスタムツールを装備する。

Agent の定義

Agent 設定を確認する。

Session

セッションのライフサイクルを管理する。

クイックスタート

5 ステップで最初の Cloud Agent を動かす。
はじめに
Agent の定義
Agent 環境の設定
Agent にタスクを委任する
Agent 連携
Agent コンテキストの管理
アカウント
ベストプラクティス
お知らせ
API リファレンス