> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent スキル

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

Skills は Agent に**ドメインの専門知識**を付与します。Skill は構造化された指示と手順のセットであり、Agent を特定のタスクにおいてより高性能かつ信頼性の高いものにします。

<Tip>
  QoderWork または Qoder デスクトップをご利用の場合、スキルマーケットプレイスから [Cloud Agents スキル](https://qoder.com/marketplace/skill?id=official_FjWvobU0) をインストールすることで、ローカルの会話から直接 Cloud Agents を作成・管理できます。手動での API 呼び出しは不要です。
</Tip>

## Skill の役割

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

## Skill のファイル構成

Skill は以下の内容を含む `.zip` アーカイブとしてアップロードします：

```
my-skill/
├── SKILL.md          # Required: Skill definition
├── templates/        # Optional: template files
│   └── report.md
└── examples/         # Optional: example files
    └── sample.json
```

`SKILL.md` はコアファイルで、YAML フロントマター + Markdown 形式で記述します：

```markdown theme={null}
name: code-review
description: Perform structured code reviews and produce improvement suggestions
version: 1.0.0

# 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 の例

```bash theme={null}
# Package the skill directory
cd my-skill && zip -r ../my-skill.zip . && cd ..

# Upload
curl -X POST https://api.qoder.com/api/v1/cloud/skills \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@my-skill.zip"
```

レスポンス：

```json theme={null}
{
  "id": "skill_019e5d133c057536872f745e0b6dbd5d",
  "type": "skill",
  "display_title": "code-review",
  "description": "Perform structured code reviews and produce improvement suggestions",
  "source": "custom",
  "latest_version": "1",
  "created_at": "2026-05-01T10:00:00Z",
  "updated_at": "2026-05-01T10:00:00Z"
}
```

<Note>
  `latest_version` はサーバーが管理し、文字列として返却されます。SKILL.md フロントマターの `version` 値（例：`1.0.0`）は情報表示用であり、サーバー側のバージョンではありません。
</Note>

## Agent への関連付け

Agent の `skills` フィールドを更新するには `POST` を使用します。楽観的同時実行制御のために `version` を含めてください。`skills` を指定すると、保存済みの skills 配列が置き換えられます。

```bash theme={null}
curl -X POST https://api.qoder.com/api/v1/cloud/agents/agent_abc123 \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1,
    "skills": [{"type": "custom", "skill_id": "skill_019e5d133c057536872f745e0b6dbd5d"}, {"type": "custom", "skill_id": "skill_019e5cdc7a9278ba933d4c328096bac5"}]
  }'
```

## バージョン管理

同名の Skill を再アップロードすると新しいバージョンが作成されます：

```bash theme={null}
# Bump the version field in SKILL.md, then re-upload
curl -X POST https://api.qoder.com/api/v1/cloud/skills \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "file=@my-skill-v2.zip"
```

Skill に関連付けられた Agent は常に最新バージョンを使用します。

## Skill の取得

```bash theme={null}
curl https://api.qoder.com/api/v1/cloud/skills/skill_019e5d133c057536872f745e0b6dbd5d \
  -H "Authorization: Bearer $QODER_PAT"
```

## Skill の一覧取得

```bash theme={null}
curl https://api.qoder.com/api/v1/cloud/skills \
  -H "Authorization: Bearer $QODER_PAT"
```

レスポンス：

```json theme={null}
{
  "data": [
    {
      "id": "skill_019e5d133c057536872f745e0b6dbd5d",
      "type": "skill",
      "display_title": "code-review",
      "description": "Perform structured code reviews and produce improvement suggestions",
      "source": "custom",
      "latest_version": "1",
      "created_at": "2026-05-01T10:00:00Z",
      "updated_at": "2026-05-01T10:00:00Z"
    },
    {
      "id": "skill_019e5cdc7a9278ba933d4c328096bac5",
      "type": "skill",
      "display_title": "doc-generator",
      "description": "Generate technical documentation",
      "source": "custom",
      "latest_version": "3",
      "created_at": "2026-04-20T08:30:00Z",
      "updated_at": "2026-04-25T09:15:00Z"
    }
  ],
  "next_page": null,
  "first_id": "skill_019e5d133c057536872f745e0b6dbd5d",
  "last_id": "skill_019e5cdc7a9278ba933d4c328096bac5",
  "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：単一の Skill zip は 10 MB 以下である必要があります。

## 次のステップ

<CardGroup cols={2}>
  <Card title="Agent ツール" icon="wrench" href="/ja/cloud-agents/tools">
    Agent に組み込み・MCP・カスタムツールを装備する。
  </Card>

  <Card title="Agent の定義" icon="user-gear" href="/ja/cloud-agents/define-agent">
    Agent 設定を確認する。
  </Card>

  <Card title="Session" icon="play" href="/ja/cloud-agents/sessions">
    セッションのライフサイクルを管理する。
  </Card>

  <Card title="クイックスタート" icon="rocket" href="/ja/cloud-agents/quickstart">
    5 ステップで最初の Cloud Agent を動かす。
  </Card>
</CardGroup>