> ## 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.

# Skill の作成

> .zip 圧縮ファイルをアップロードして Skill を作成します。

`POST /api/v1/cloud/skills`

新しい Skill リソースをアップロードして作成します。Skill の内容は `multipart/form-data` エンコーディングを使用し、`.zip` 圧縮ファイルとしてアップロードする必要があります。

## ヘッダー

| ヘッダー            | 必須  | 説明                                                      |
| --------------- | --- | ------------------------------------------------------- |
| `Authorization` | はい  | `Bearer $QODER_PAT`                                     |
| `Content-Type`  | いいえ | `curl -F` により自動的に `multipart/form-data` に設定されるため、手動指定不要 |

## リクエストボディ（multipart/form-data）

| フィールド         | 型           | 必須  | 説明                                                                 |
| ------------- | ----------- | --- | ------------------------------------------------------------------ |
| `file`        | file        | はい  | Skill 内容の `.zip` 圧縮ファイル、最大 5 MB                                    |
| `name`        | string      | いいえ | 互換性のために受け付けますが、API は `SKILL.md` frontmatter の `name` を使用します        |
| `type`        | string      | いいえ | Skill タイプ。値：`custom`、`prebuilt`（デフォルト `custom`）                    |
| `description` | string      | いいえ | 互換性のために受け付けますが、API は `SKILL.md` frontmatter の `description` を使用します |
| `metadata`    | JSON string | いいえ | JSON オブジェクト形式のカスタムメタデータ                                            |

## zip ファイル構造

圧縮ファイルには、アーカイブルートまたはルートの 1 階層下に `SKILL.md` を含める必要があります。`SKILL.md` は以下の形式の YAML frontmatter で始まる必要があります:

```text theme={null}
---
name: my-skill
description: Skill description
version: 1.0.0
---

# Skill title

## Steps
1. Step one
2. Step two
```

zip エントリパスは `/` または Windows 形式の `\` セパレータを使用できます。サービスは `SKILL.md` を検索する際にパスを正規化します。

## リクエスト例

```bash theme={null}
# Prepare skill content
mkdir my-skill && cat > my-skill/SKILL.md << 'EOF'
---
name: my-custom-skill
description: Custom skill example
version: 1.0.0
---

# My Custom Skill

## Steps
1. Perform action A
2. Perform action B

## Verification
Confirm the operation completed.
EOF

# Pack as zip
cd my-skill && zip ../my-skill.zip SKILL.md && cd ..

# Upload to create
curl -X POST https://api.qoder.com/api/v1/cloud/skills \
  -H "Authorization: Bearer $QODER_PAT" \
  -F "name=my-custom-skill" \
  -F "type=custom" \
  -F 'metadata={"team":"docs"}' \
  -F "description=Custom skill example" \
  -F "file=@my-skill.zip"
```

## レスポンス例

**HTTP 201 Created**

```json theme={null}
{
  "id": "skill_019e3bba474b73cfaf19eae9b5f5e66d",
  "type": "skill",
  "display_title": "my-custom-skill",
  "description": "Custom skill example",
  "source": "custom",
  "latest_version": "1",
  "metadata": {
    "team": "docs"
  },
  "created_at": "2026-05-18T15:35:24.248164Z",
  "updated_at": "2026-05-18T15:35:24.248164Z"
}
```

## レスポンスフィールド

| フィールド            | 型      | 説明                                      |
| ---------------- | ------ | --------------------------------------- |
| `id`             | string | `skill_` プレフィックス付きの Skill 一意識別子         |
| `type`           | string | 固定値 `"skill"`                           |
| `display_title`  | string | 保存された Skill 名から導出される表示タイトル              |
| `description`    | string | Skill の説明                               |
| `source`         | string | Skill のソース：`custom` または `qoder`         |
| `latest_version` | string | 文字列形式の最新バージョン番号                         |
| `metadata`       | object | Skill に保存されるカスタムメタデータオブジェクト。デフォルトは `{}` |
| `created_at`     | string | 作成時刻（ISO 8601）                          |
| `updated_at`     | string | 最終更新時刻（ISO 8601）                        |

## エラーレスポンス

| HTTP | type                    | 説明                                                                |
| ---- | ----------------------- | ----------------------------------------------------------------- |
| 400  | `invalid_request_error` | 非 multipart リクエスト: "Invalid multipart form or request too large." |
| 400  | `invalid_request_error` | `file` フィールド欠落: "Field 'file' is required."                       |
| 400  | `invalid_request_error` | 非 zip 形式: "Only .zip files are accepted."                         |
| 401  | `TOKEN_INVALID`         | 認証トークンが欠落または無効                                                    |

## 注意事項

* 同名の Skill 作成が許可されます（名前の一意性は強制されません）
* `name` と `description` は常に `SKILL.md` frontmatter から読み取られます。フォーム値はアーカイブ内容を上書きしません
* Skill 名は最大 64 文字で、小文字、数字、ハイフン（`-`）、アンダースコア（`_`）のみ使用可能で、英字または数字で始まる必要があります
* Windows で作成された zip アーカイブもサポートされます。バックスラッシュのパスセパレータは正規化されます
* 初期バージョン番号は 1 です
* JSON Content-Type はサポートされず、`multipart/form-data` が必須です

完全なエラーエンベロープについては [エラー](/ja/cloud-agents/api/conventions/errors) を参照してください。

## 関連項目

<CardGroup cols={2}>
  <Card title="Agent スキル" icon="sparkles" href="/ja/cloud-agents/skills">
    Agent にドメインの専門知識を付与する。
  </Card>
</CardGroup>