メインコンテンツへスキップ
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）

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

​
zip ファイル構造

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

# Skill title

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

​
リクエスト例

# 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 
{
  "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"
}

​
レスポンスフィールド

フィールド型説明
idstringskill_ プレフィックス付きの Skill 一意識別子
typestring固定値 "skill"
display_titlestring保存された Skill 名から導出される表示タイトル
descriptionstringSkill の説明
sourcestringSkill のソース：custom または qoder
latest_versionstring文字列形式の最新バージョン番号
metadataobjectSkill に保存されるカスタムメタデータオブジェクト。デフォルトは {}
created_atstring作成時刻（ISO 8601）
updated_atstring最終更新時刻（ISO 8601）

​
エラーレスポンス

HTTPtype説明
400invalid_request_error非 multipart リクエスト: “Invalid multipart form or request too large.”
400invalid_request_errorfile フィールド欠落: “Field ‘file’ is required.”
400invalid_request_error非 zip 形式: “Only .zip files are accepted.”
401TOKEN_INVALID認証トークンが欠落または無効

​
注意事項

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

​
関連項目

Agent スキル

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