Skip to main content
Skills

Skill の作成

新しい Skill リソースを最初のバージョンとともにアップロードして作成する。

POST /api/v1/cloud/skills 新しい Skill リソースを、最初の不変なバージョンスナップショットとともにアップロードして作成します。multipart/form-data エンコーディングを使用し、files フィールドから .zip アーカイブまたはベアファイルツリーとして内容をアップロードします。

ヘッダー

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

リクエストボディ(multipart/form-data)

フィールド必須説明
filesfile(繰り返し可)はいSkill の内容。単一の .zip アーカイブ、または相対パスを filename に含む複数 part のベアファイルツリー。どちらもトップレベルディレクトリは 1 つで、その名前が SKILL.mdname と一致する必要があります
display_titlestringいいえ表示タイトル。一意性は強制されません。省略時は zip ファイル名または SKILL.mdname を使用します。作成後は変更できません
metadataJSON stringいいえJSON オブジェクト形式のカスタムメタデータ
filefileいいえ⚠️ 非推奨:従来の単一 zip フィールド(代わりに files を使用)
namestringいいえ⚠️ 非推奨:現在は display_title にマッピングされます(代わりに display_title を使用。モデルが認識する Skill 名は常に SKILL.md frontmatter の name から取得)
descriptionstringいいえ⚠️ 非推奨:このフィールドは無効です。説明は常に SKILL.md frontmatter から読み取られます(代替なし)
typestringいいえ⚠️ 非推奨custom / prebuilt、デフォルトは custom。今後削除され、作成される Skill はすべて custom になります

パッケージルール

コンテンツパッケージには 1 つのトップレベルディレクトリが必要です。その名前は SKILL.mdname と一致し、ディレクトリ内の SKILL.md は YAML frontmatter で始まる必要があります。frontmatter の制約、サイズ制限、解析動作などの完全なルールは Skill パッケージ を参照してください。

リクエスト例

# Prepare skill content
mkdir my-custom-skill && cat > my-custom-skill/SKILL.md << 'EOF'
---
name: my-custom-skill
description: Custom skill example
---

# My Custom Skill

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

## Verification
Confirm the operation completed.
EOF

# Pack as zip (keep the top-level directory)
zip -r my-custom-skill.zip my-custom-skill/

# Upload to create
curl -X POST "https://api.qoder.com/api/v1/cloud/skills" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "display_title=My Custom Skill" \
  -F 'metadata={"team":"docs"}' \
  -F "files=@my-custom-skill.zip"
ベアファイルツリーをアップロードする場合(zip を使わず、filename に相対パスを含める):
curl -X POST "https://api.qoder.com/api/v1/cloud/skills" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "files=@my-custom-skill/SKILL.md;filename=my-custom-skill/SKILL.md" \
  -F "files=@my-custom-skill/templates/report.md;filename=my-custom-skill/templates/report.md"

レスポンス例

HTTP 201 Created
{
  "id": "skill_019e3bba474b73cfaf19eae9b5f5e66d",
  "type": "skill",
  "display_title": "My Custom Skill",
  "source": "custom",
  "latest_version": "1759178010641129",
  "metadata": {
    "team": "docs"
  },
  "created_at": "2026-05-18T15:35:24.248164Z",
  "updated_at": "2026-05-18T15:35:24.248164Z"
}

レスポンスフィールド

レスポンスは Skill オブジェクト です。
フィールド説明
idstringskill_ プレフィックス付きの Skill 一意識別子
typestring固定値 "skill"
display_titlestring表示タイトル
sourcestringSkill のソース:custom または qoder
latest_versionstring最新バージョン識別子
metadataobjectSkill に保存されるカスタムメタデータオブジェクト。デフォルトは {}
created_atstring作成時刻
updated_atstring最終更新時刻

エラーレスポンス

HTTPtype説明
400invalid_request_errormultipart 以外のリクエスト、files フィールドの欠落、または Skill パッケージ ルールに違反するコンテンツパッケージ
401TOKEN_INVALID認証トークンが欠落または無効
413request_too_large_errorアーカイブが 50 MB を超えている
429rate_limit_errorレート制限またはクォータ制限に達した

注意事項

  • モデルが認識する Skill 名は常に SKILL.md frontmatter の name から取得され、display_title とは独立しています。
  • name は同じ Skill の後続すべてのバージョンで一致する必要があります(Skill バージョンの作成 を参照)。
完全なエラーエンベロープについては エラー を参照してください。

関連項目