Skill レスポンスとパッケージの共通構造。
Skill オブジェクト
create、get、list エンドポイントが返す構造（Skill シェル）です。
| フィールド | 型 | 説明 |
|---|---|---|
id | string | skill_ プレフィックス付きの Skill ID |
type | string | 固定値 "skill" |
display_title | string | 表示タイトル（最大 255 文字。一意性は強制されず、作成後は変更不可）。デフォルト値：zip アップロードでは .zip を除いた zip ファイル名、ベアファイルツリーでは SKILL.md の name |
source | string | 有効な値：custom、qoder |
latest_version | string | null | 最新バージョンを表す epoch マイクロ秒文字列（例："1759178010641129"）。すべてのバージョンが削除されると null |
metadata | object | Skill に保存されるカスタムメタデータオブジェクト。デフォルトは {} |
created_at | string | 作成時刻（ISO 8601、マイクロ秒精度。例：2026-05-18T15:35:24.248164Z） |
updated_at | string | 最終更新時刻（ISO 8601、マイクロ秒精度）。バージョンの作成または削除時に更新 |
description | string | ⚠️ 非推奨：Skill の説明（代わりにバージョンオブジェクトの description を使用） |
content | string | ⚠️ 非推奨：base64 エンコードされた内容。include_content=true の場合のみ存在（代わりに GET /skills/{skill_id}/versions/{version}/content を使用） |
content_encoding | string | ⚠️ 非推奨：content とともに存在し、値は base64（代替は上記と同じ） |
Skill バージョンオブジェクト
バージョンの作成、バージョンの取得、バージョン一覧が返す構造です。各バージョンは不変の完全なコンテンツスナップショットです。
| フィールド | 型 | 説明 |
|---|---|---|
id | string | バージョン ID |
type | string | 常に "skill_version" |
skill_id | string | 所属する Skill の ID |
version | string | 作成時刻の epoch マイクロ秒文字列であるバージョン識別子（例："1759178010641129"） |
name | string | このバージョンの SKILL.md frontmatter にある name。すべてのバージョンで一致する必要があります |
description | string | このバージョンの SKILL.md frontmatter にある description |
directory | string | サンドボックスへのインストールディレクトリ名。常に name と同じ |
created_at | string | バージョン作成時刻（ISO 8601、マイクロ秒精度） |
content_size | integer | ⚠️ 非推奨：コンテンツサイズ（バイト）（代替なし。今後削除予定） |
content_sha256 | string | ⚠️ 非推奨：SHA-256 ダイジェスト（代替なし。今後削除予定） |
status | string | ⚠️ 非推奨：バージョン状態（代替なし。今後削除予定） |
updated_at | string | ⚠️ 非推奨：最終更新時刻（バージョンは不変のため、代わりに created_at を使用） |
Skill パッケージ
Skill 作成およびバージョン作成リクエストは、multipart/form-data の files フィールドから .zip アーカイブまたはベアファイルツリーをアップロードします。
| ルール | 説明 |
|---|---|
| アップロード形式 | 単一の .zip アーカイブ、または相対パスを filename に含む複数の files part からなるベアファイルツリー |
| サイズ制限 | アーカイブは 50 MB 以下、展開後の内容も 50 MB 以下 |
| トップレベルディレクトリ | 1 つのトップレベルディレクトリが必要で、その名前は SKILL.md の name と一致する必要があります。一致しない場合は 400 |
| 必須マニフェスト | トップレベルディレクトリ内に、YAML frontmatter で始まる SKILL.md を配置 |
frontmatter name | 必須かつ空でないこと。最大 64 文字。^[a-z0-9][a-z0-9_-]*$ に一致し、同じ Skill のすべてのバージョンで同一であること |
frontmatter description | 必須かつ空でないこと。最大 5120 文字 |
| frontmatter の解析 | 最初に厳密な YAML として解析し、失敗時はトップレベルの name: / description: を行単位で抽出し、その他のキーを無視する緩やかなフォールバックを使用。値に ': ' を含む場合は引用符で囲むことを推奨 |