> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/api/ja/api-reference/ji-neng.md).

# スキル

### スキルのアップロード <a href="#skills-upload-create" id="skills-upload-create"></a>

POST `/api/v1/skills/upload/`

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出し例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/skills/upload/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -F "file=@example_file.pdf" \
  -F "attached_tool_ids=サンプル文字列"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');
const FormData = require('form-data');

// FormData オブジェクトを作成します
const formData = new FormData();
// 実際のファイルに置き換えてください
formData.append('file', /* 実際のファイルオブジェクト */, 'example_file.pdf');
formData.append('attached_tool_ids', 'サンプル文字列');

// リクエストヘッダーを設定します
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    ...formData.getHeaders()
  }
};

axios.post("https://api.maiagent.ai/api/v1/skills/upload/", formData, config)
  .then(response => {
    console.log('レスポンスを取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/skills/upload/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}

# ファイルとフォームデータを作成します
files = {
    'file': ('example_file.pdf', open('example_file.pdf', 'rb'), 'application/pdf'),
    'attached_tool_ids': (None, 'サンプル文字列')
}

response = requests.post(url, files=files, headers=headers)
try:
    print("レスポンスを取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/skills/upload/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ],
        'multipart' => [
            [
                'name' => 'file',
                'contents' => fopen('example_file.pdf', 'r'),
                'filename' => 'example_file.pdf'
            ],
            [
                'name' => 'attached_tool_ids',
                'contents' => 'サンプル文字列'
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンスボディ

**ステータスコード: 201**

**レスポンススキーマの例**

```typescript
{
  "id"?: string (uuid) // 任意
  "name"?: string // 任意
  "description"?: string // 任意
  "attached_tools"?: [ // スキルパッケージの frontmatter に基づいて自動的に関連付けられたツールの名前です (任意)
    string
  ]
  "missing_tools"?: [ // スキルパッケージで宣言されていますが、この組織に同名のツールがなく、手動で関連付ける必要があるツールの名前です (任意)
    string
  ]
  "message"?: string // 任意
}
```

**レスポンス値の例**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "レスポンス文字列",
  "description": "レスポンス文字列",
  "attached_tools": [
    "レスポンス文字列"
  ],
  "missing_tools": [
    "レスポンス文字列"
  ],
  "message": "レスポンス文字列"
}
```

**ステータスコード: 400**

**レスポンススキーマの例**

```typescript
{
  "detail"?: string // エラーメッセージ (任意)
}
```

**レスポンス値の例**

```json
{
  "detail": "レスポンス文字列"
}
```

***

### スキルの作成 <a href="#skills-create" id="skills-create"></a>

POST `/api/v1/skills/`

#### リクエストボディ

**リクエストパラメータ**

| フィールド           | 型              | 必須  | 説明                                                                                                                                      |
| --------------- | -------------- | --- | --------------------------------------------------------------------------------------------------------------------------------------- |
| name            | string         | はい  |                                                                                                                                         |
| description     | string         | はい  |                                                                                                                                         |
| whenToUse       | string         | いいえ | Describe when the LLM should trigger this skill. Max 200 characters recommended.                                                        |
| instructions    | string         | いいえ | Markdown text with instructions for the skill                                                                                           |
| attachedToolIds | array\[string] | いいえ |                                                                                                                                         |
| groups          | array\[IdName] | いいえ | Groups this skill is assigned to. Non-owner members must pick at least one group they belong to.                                        |
| files           | array\[object] | いいえ | Optional resource files to create with the skill. Each item must include path and content. content\_encoding may be "text" or "base64". |

**リクエストスキーマの例**

```typescript
{
  "name": string
  "description": string
  "whenToUse"?: string // Describe when the LLM should trigger this skill. Max 200 characters recommended. (任意)
  "instructions"?: string // Markdown text with instructions for the skill (任意)
  "attachedToolIds"?: [ // 任意
    string (uuid)
  ]
  "groups"?: [ // Groups this skill is assigned to. Non-owner members must pick at least one group they belong to. (任意)
    {
      "id": string (uuid)
    }
  ]
  "files"?: [ // Optional resource files to create with the skill. Each item must include path and content. content_encoding may be "text" or "base64". (任意)
    object
  ]
}
```

**リクエスト値の例**

```json
{
  "name": "サンプル名",
  "description": "サンプル文字列",
  "whenToUse": "サンプル文字列",
  "instructions": "サンプル文字列",
  "attachedToolIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "files": [
    {}
  ]
}
```

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出し例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/skills/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "サンプル名",
    "description": "サンプル文字列",
    "whenToUse": "サンプル文字列",
    "instructions": "サンプル文字列",
    "attachedToolIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "files": [
      {}
    ]
  }'

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定します
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// リクエストボディ (payload)
const data = {
    "name": "サンプル名",
    "description": "サンプル文字列",
    "whenToUse": "サンプル文字列",
    "instructions": "サンプル文字列",
    "attachedToolIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ],
    "files": [
      {}
    ]
  };

axios.post("https://api.maiagent.ai/api/v1/skills/", data, config)
  .then(response => {
    console.log('レスポンスを取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/skills/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# リクエストボディ (payload)
data = {
    "name": "サンプル名",
    "description": "サンプル文字列",
    "whenToUse": "サンプル文字列",
    "instructions": "サンプル文字列",
    "attachedToolIds": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "groups": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ],
    "files": [
        {}
    ]
}

response = requests.post(url, json=data, headers=headers)
try:
    print("レスポンスを取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/skills/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => 'サンプル名',
            'description' => 'サンプル文字列',
            'whenToUse' => 'サンプル文字列',
            'instructions' => 'サンプル文字列',
            'attachedToolIds' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'groups' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ],
            'files' => [
                new \stdClass()
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンスボディ

**ステータスコード: 201**

**レスポンススキーマの例**

```typescript
{
  "id": string (uuid)
  "name": string
  "description": string
  "whenToUse": string // Describe when the LLM should trigger this skill. Max 200 characters recommended.
  "instructions": string // Markdown text with instructions for the skill
  "compatibility": string // Optional environment requirements from the Agent Skills Spec frontmatter (max 500 chars).
  "metadata": object // Optional arbitrary key-value mapping from the Agent Skills Spec frontmatter.
  "allowedTools": object // Optional pre-approved tool list from the Agent Skills Spec frontmatter (experimental).
  "source":  // How the skill was created: upload (.skill/.zip) or manual

* `upload` - Upload
* `manual` - Manual
  {
  }
  "skillPackagePath": string // S3 path for the uploaded .skill/.zip file
  "skillPackageName": string // Original filename of the uploaded skill package
  "skillPackageSize": integer // Size of the uploaded skill package in bytes
  "skillPackageUploadedAt": string (timestamp)
  "attachedTools": [
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "resources": [
    {
      "id": string (uuid)
      "path": string // Relative path within the skill directory, e.g. scripts/helper.py
      "filePath": string // S3 path: skills/{organization_id}/{skill_id}/resources/
      "fileSize": integer // File size in bytes
      "mimeType": string
      "createdAt": string (timestamp)
    }
  ]
  "groups": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
  "lastUsedAt": string (timestamp)
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
}
```

**レスポンス値の例**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "レスポンス文字列",
  "description": "レスポンス文字列",
  "whenToUse": "レスポンス文字列",
  "instructions": "レスポンス文字列",
  "compatibility": "レスポンス文字列",
  "metadata": null,
  "allowedTools": null,
  "source": {},
  "skillPackagePath": "レスポンス文字列",
  "skillPackageName": "レスポンス文字列",
  "skillPackageSize": 456,
  "skillPackageUploadedAt": "レスポンス文字列",
  "attachedTools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "レスポンス文字列",
      "description": "レスポンス文字列",
      "displayName": "レスポンス文字列",
      "toolType": "レスポンス文字列"
    }
  ],
  "resources": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "path": "レスポンス文字列",
      "filePath": "レスポンス文字列",
      "fileSize": 456,
      "mimeType": "レスポンス文字列",
      "createdAt": "レスポンス文字列"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "レスポンス文字列"
    }
  ],
  "createdAt": "レスポンス文字列",
  "updatedAt": "レスポンス文字列",
  "lastUsedAt": "レスポンス文字列",
  "canUpdate": false,
  "canDelete": false
}
```

***

### スキル一覧の取得 <a href="#skills-list" id="skills-list"></a>

GET `/api/v1/skills/`

#### パラメータ

| パラメータ名     | 必須 | 型       | 説明                                             |
| ---------- | -- | ------- | ---------------------------------------------- |
| `isActive` | ❌  | boolean |                                                |
| `page`     | ❌  | integer | A page number within the paginated result set. |
| `pageSize` | ❌  | integer | Number of results to return per page.          |
| `search`   | ❌  | string  |                                                |

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出しの例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/skills/?isActive=true&page=1&pageSize=1&search=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定します
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/skills/?isActive=true&page=1&pageSize=1&search=example", config)
  .then(response => {
    console.log('レスポンスを取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/skills/?isActive=true&page=1&pageSize=1&search=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("レスポンスを取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/skills/?isActive=true&page=1&pageSize=1&search=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンスボディ

**ステータスコード: 200**

**レスポンススキーマの例**

```typescript
{
  "count": integer
  "next"?: string (uri) // 任意
  "previous"?: string (uri) // 任意
  "results": [
    {
      "id": string (uuid)
      "name": string
      "description": string
      "whenToUse": string // Describe when the LLM should trigger this skill. Max 200 characters recommended.
      "source":  // How the skill was created: upload (.skill/.zip) or manual

* `upload` - Upload
* `manual` - Manual
      {
      }
      "attachedTools": [
        {
          "id": string (uuid)
          "name": string
          "description": string
          "displayName": string
          "toolType": string
        }
      ]
      "groups": [
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "createdBy": object // Show 'System' as the creator for global skills (uploaded by platform staff).
      "createdAt": string (timestamp)
      "updatedAt": string (timestamp)
      "lastUsedAt": string (timestamp)
      "canUpdate": boolean // Return whether the current user can update this resource.
      "canDelete": boolean // Return whether the current user can delete this resource.
    }
  ]
}
```

**レスポンス値の例**

```json
{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "レスポンス文字列",
      "description": "レスポンス文字列",
      "whenToUse": "レスポンス文字列",
      "source": {},
      "attachedTools": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "レスポンス文字列",
          "description": "レスポンス文字列",
          "displayName": "レスポンス文字列",
          "toolType": "レスポンス文字列"
        }
      ],
      "groups": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "レスポンス文字列"
        }
      ],
      "createdBy": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "レスポンス例の名前",
        "description": "レスポンス例の説明"
      },
      "createdAt": "レスポンス文字列",
      "updatedAt": "レスポンス文字列",
      "lastUsedAt": "レスポンス文字列",
      "canUpdate": false,
      "canDelete": false
    }
  ]
}
```

***

### 特定のスキルの取得 <a href="#skills-retrieve" id="skills-retrieve"></a>

GET `/api/v1/skills/{id}/`

#### パラメータ

| パラメータ名 | 必須 | 型      | 説明                                    |
| ------ | -- | ------ | ------------------------------------- |
| `id`   | ✅  | string | A UUID string identifying this Skill. |

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定します
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/", config)
  .then(response => {
    console.log('レスポンスを取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("レスポンスを取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンスボディ

**ステータスコード: 200**

**レスポンススキーマの例**

```typescript
{
  "id": string (uuid)
  "name": string
  "description": string
  "whenToUse": string // Describe when the LLM should trigger this skill. Max 200 characters recommended.
  "instructions": string // Markdown text with instructions for the skill
  "compatibility": string // Optional environment requirements from the Agent Skills Spec frontmatter (max 500 chars).
  "metadata": object // Optional arbitrary key-value mapping from the Agent Skills Spec frontmatter.
  "allowedTools": object // Optional pre-approved tool list from the Agent Skills Spec frontmatter (experimental).
  "source":  // How the skill was created: upload (.skill/.zip) or manual

* `upload` - Upload
* `manual` - Manual
  {
  }
  "skillPackagePath": string // S3 path for the uploaded .skill/.zip file
  "skillPackageName": string // Original filename of the uploaded skill package
  "skillPackageSize": integer // Size of the uploaded skill package in bytes
  "skillPackageUploadedAt": string (timestamp)
  "attachedTools": [
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "resources": [
    {
      "id": string (uuid)
      "path": string // Relative path within the skill directory, e.g. scripts/helper.py
      "filePath": string // S3 path: skills/{organization_id}/{skill_id}/resources/
      "fileSize": integer // File size in bytes
      "mimeType": string
      "createdAt": string (timestamp)
    }
  ]
  "groups": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
  "lastUsedAt": string (timestamp)
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
}
```

**レスポンス値の例**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "レスポンス文字列",
  "description": "レスポンス文字列",
  "whenToUse": "レスポンス文字列",
  "instructions": "レスポンス文字列",
  "compatibility": "レスポンス文字列",
  "metadata": null,
  "allowedTools": null,
  "source": {},
  "skillPackagePath": "レスポンス文字列",
  "skillPackageName": "レスポンス文字列",
  "skillPackageSize": 456,
  "skillPackageUploadedAt": "レスポンス文字列",
  "attachedTools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "レスポンス文字列",
      "description": "レスポンス文字列",
      "displayName": "レスポンス文字列",
      "toolType": "レスポンス文字列"
    }
  ],
  "resources": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "path": "レスポンス文字列",
      "filePath": "レスポンス文字列",
      "fileSize": 456,
      "mimeType": "レスポンス文字列",
      "createdAt": "レスポンス文字列"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "レスポンス文字列"
    }
  ],
  "createdAt": "レスポンス文字列",
  "updatedAt": "レスポンス文字列",
  "lastUsedAt": "レスポンス文字列",
  "canUpdate": false,
  "canDelete": false
}
```

***

### スキルの更新 <a href="#skills-update" id="skills-update"></a>

PUT `/api/v1/skills/{id}/`

#### パラメータ

| パラメータ名 | 必須 | 型      | 説明                                    |
| ------ | -- | ------ | ------------------------------------- |
| `id`   | ✅  | string | A UUID string identifying this Skill. |

#### リクエストボディ

**リクエストパラメータ**

| フィールド           | 型              | 必須  | 説明                                                                                               |
| --------------- | -------------- | --- | ------------------------------------------------------------------------------------------------ |
| name            | string         | はい  |                                                                                                  |
| description     | string         | はい  |                                                                                                  |
| whenToUse       | string         | いいえ | Describe when the LLM should trigger this skill. Max 200 characters recommended.                 |
| instructions    | string         | いいえ | Markdown text with instructions for the skill                                                    |
| attachedToolIds | array\[string] | いいえ |                                                                                                  |
| groups          | array\[IdName] | いいえ | Groups this skill is assigned to. Non-owner members must pick at least one group they belong to. |

**リクエスト構造の例**

```typescript
{
  "name": string
  "description": string
  "whenToUse"?: string // Describe when the LLM should trigger this skill. Max 200 characters recommended. (任意)
  "instructions"?: string // Markdown text with instructions for the skill (任意)
  "attachedToolIds"?: [ // 任意
    string (uuid)
  ]
  "groups"?: [ // Groups this skill is assigned to. Non-owner members must pick at least one group they belong to. (任意)
    {
      "id": string (uuid)
    }
  ]
}
```

**リクエスト値の例**

```json
{
  "name": "サンプル名",
  "description": "サンプル文字列",
  "whenToUse": "サンプル文字列",
  "instructions": "サンプル文字列",
  "attachedToolIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}
```

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出しの例 (Shell)
curl -X PUT "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "サンプル名",
    "description": "サンプル文字列",
    "whenToUse": "サンプル文字列",
    "instructions": "サンプル文字列",
    "attachedToolIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  }'

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定します
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// リクエストボディ (payload)
const data = {
    "name": "サンプル名",
    "description": "サンプル文字列",
    "whenToUse": "サンプル文字列",
    "instructions": "サンプル文字列",
    "attachedToolIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  };

axios.put("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# リクエストボディ (payload)
data = {
    "name": "サンプル名",
    "description": "サンプル文字列",
    "whenToUse": "サンプル文字列",
    "instructions": "サンプル文字列",
    "attachedToolIds": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "groups": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ]
}

response = requests.put(url, json=data, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->put("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => 'サンプル名',
            'description' => 'サンプル文字列',
            'whenToUse' => 'サンプル文字列',
            'instructions' => 'サンプル文字列',
            'attachedToolIds' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'groups' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンスボディ

**ステータスコード: 200**

**レスポンス構造の例**

```typescript
{
  "id": string (uuid)
  "name": string
  "description": string
  "whenToUse": string // Describe when the LLM should trigger this skill. Max 200 characters recommended.
  "instructions": string // Markdown text with instructions for the skill
  "compatibility": string // Optional environment requirements from the Agent Skills Spec frontmatter (max 500 chars).
  "metadata": object // Optional arbitrary key-value mapping from the Agent Skills Spec frontmatter.
  "allowedTools": object // Optional pre-approved tool list from the Agent Skills Spec frontmatter (experimental).
  "source":  // How the skill was created: upload (.skill/.zip) or manual

* `upload` - Upload
* `manual` - Manual
  {
  }
  "skillPackagePath": string // S3 path for the uploaded .skill/.zip file
  "skillPackageName": string // Original filename of the uploaded skill package
  "skillPackageSize": integer // Size of the uploaded skill package in bytes
  "skillPackageUploadedAt": string (timestamp)
  "attachedTools": [
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "resources": [
    {
      "id": string (uuid)
      "path": string // Relative path within the skill directory, e.g. scripts/helper.py
      "filePath": string // S3 path: skills/{organization_id}/{skill_id}/resources/
      "fileSize": integer // File size in bytes
      "mimeType": string
      "createdAt": string (timestamp)
    }
  ]
  "groups": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
  "lastUsedAt": string (timestamp)
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
}
```

**レスポンス値の例**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "レスポンス文字列",
  "description": "レスポンス文字列",
  "whenToUse": "レスポンス文字列",
  "instructions": "レスポンス文字列",
  "compatibility": "レスポンス文字列",
  "metadata": null,
  "allowedTools": null,
  "source": {},
  "skillPackagePath": "レスポンス文字列",
  "skillPackageName": "レスポンス文字列",
  "skillPackageSize": 456,
  "skillPackageUploadedAt": "レスポンス文字列",
  "attachedTools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "レスポンス文字列",
      "description": "レスポンス文字列",
      "displayName": "レスポンス文字列",
      "toolType": "レスポンス文字列"
    }
  ],
  "resources": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "path": "レスポンス文字列",
      "filePath": "レスポンス文字列",
      "fileSize": 456,
      "mimeType": "レスポンス文字列",
      "createdAt": "レスポンス文字列"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "レスポンス文字列"
    }
  ],
  "createdAt": "レスポンス文字列",
  "updatedAt": "レスポンス文字列",
  "lastUsedAt": "レスポンス文字列",
  "canUpdate": false,
  "canDelete": false
}
```

***

### スキルの部分更新 <a href="#skills-partial-update" id="skills-partial-update"></a>

PATCH `/api/v1/skills/{id}/`

#### パラメータ

| パラメータ名 | 必須 | 型      | 説明                                    |
| ------ | -- | ------ | ------------------------------------- |
| `id`   | ✅  | string | A UUID string identifying this Skill. |

#### リクエストボディ

**リクエストパラメータ**

| フィールド           | 型              | 必須  | 説明                                                                                               |
| --------------- | -------------- | --- | ------------------------------------------------------------------------------------------------ |
| name            | string         | いいえ |                                                                                                  |
| description     | string         | いいえ |                                                                                                  |
| whenToUse       | string         | いいえ | Describe when the LLM should trigger this skill. Max 200 characters recommended.                 |
| instructions    | string         | いいえ | Markdown text with instructions for the skill                                                    |
| attachedToolIds | array\[string] | いいえ |                                                                                                  |
| groups          | array\[IdName] | いいえ | Groups this skill is assigned to. Non-owner members must pick at least one group they belong to. |

**リクエスト構造の例**

```typescript
{
  "name"?: string // 任意
  "description"?: string // 任意
  "whenToUse"?: string // Describe when the LLM should trigger this skill. Max 200 characters recommended. (任意)
  "instructions"?: string // Markdown text with instructions for the skill (任意)
  "attachedToolIds"?: [ // 任意
    string (uuid)
  ]
  "groups"?: [ // Groups this skill is assigned to. Non-owner members must pick at least one group they belong to. (任意)
    {
      "id": string (uuid)
    }
  ]
}
```

**リクエスト値の例**

```json
{
  "name": "サンプル名",
  "description": "サンプル文字列",
  "whenToUse": "サンプル文字列",
  "instructions": "サンプル文字列",
  "attachedToolIds": [
    "550e8400-e29b-41d4-a716-446655440000"
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}
```

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出しの例 (Shell)
curl -X PATCH "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "サンプル名",
    "description": "サンプル文字列",
    "whenToUse": "サンプル文字列",
    "instructions": "サンプル文字列",
    "attachedToolIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  }'

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定します
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// リクエストボディ (payload)
const data = {
    "name": "サンプル名",
    "description": "サンプル文字列",
    "whenToUse": "サンプル文字列",
    "instructions": "サンプル文字列",
    "attachedToolIds": [
      "550e8400-e29b-41d4-a716-446655440000"
    ],
    "groups": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  };

axios.patch("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# リクエストボディ (payload)
data = {
    "name": "サンプル名",
    "description": "サンプル文字列",
    "whenToUse": "サンプル文字列",
    "instructions": "サンプル文字列",
    "attachedToolIds": [
        "550e8400-e29b-41d4-a716-446655440000"
    ],
    "groups": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000"
        }
    ]
}

response = requests.patch(url, json=data, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->patch("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => [
            'name' => 'サンプル名',
            'description' => 'サンプル文字列',
            'whenToUse' => 'サンプル文字列',
            'instructions' => 'サンプル文字列',
            'attachedToolIds' => [
                '550e8400-e29b-41d4-a716-446655440000'
            ],
            'groups' => [
                [
                    'id' => '550e8400-e29b-41d4-a716-446655440000'
                ]
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンスボディ

**ステータスコード: 200**

**レスポンス構造の例**

```typescript
{
  "id": string (uuid)
  "name": string
  "description": string
  "whenToUse": string // Describe when the LLM should trigger this skill. Max 200 characters recommended.
  "instructions": string // Markdown text with instructions for the skill
  "compatibility": string // Optional environment requirements from the Agent Skills Spec frontmatter (max 500 chars).
  "metadata": object // Optional arbitrary key-value mapping from the Agent Skills Spec frontmatter.
  "allowedTools": object // Optional pre-approved tool list from the Agent Skills Spec frontmatter (experimental).
  "source":  // How the skill was created: upload (.skill/.zip) or manual

* `upload` - Upload
* `manual` - Manual
  {
  }
  "skillPackagePath": string // S3 path for the uploaded .skill/.zip file
  "skillPackageName": string // Original filename of the uploaded skill package
  "skillPackageSize": integer // Size of the uploaded skill package in bytes
  "skillPackageUploadedAt": string (timestamp)
  "attachedTools": [
    {
      "id": string (uuid)
      "name": string
      "description": string
      "displayName": string
      "toolType": string
    }
  ]
  "resources": [
    {
      "id": string (uuid)
      "path": string // Relative path within the skill directory, e.g. scripts/helper.py
      "filePath": string // S3 path: skills/{organization_id}/{skill_id}/resources/
      "fileSize": integer // File size in bytes
      "mimeType": string
      "createdAt": string (timestamp)
    }
  ]
  "groups": [
    {
      "id": string (uuid)
      "name": string
    }
  ]
  "createdAt": string (timestamp)
  "updatedAt": string (timestamp)
  "lastUsedAt": string (timestamp)
  "canUpdate": boolean // Return whether the current user can update this resource.
  "canDelete": boolean // Return whether the current user can delete this resource.
}
```

**レスポンス値の例**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "レスポンス文字列",
  "description": "レスポンス文字列",
  "whenToUse": "レスポンス文字列",
  "instructions": "レスポンス文字列",
  "compatibility": "レスポンス文字列",
  "metadata": null,
  "allowedTools": null,
  "source": {},
  "skillPackagePath": "レスポンス文字列",
  "skillPackageName": "レスポンス文字列",
  "skillPackageSize": 456,
  "skillPackageUploadedAt": "レスポンス文字列",
  "attachedTools": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "レスポンス文字列",
      "description": "レスポンス文字列",
      "displayName": "レスポンス文字列",
      "toolType": "レスポンス文字列"
    }
  ],
  "resources": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "path": "レスポンス文字列",
      "filePath": "レスポンス文字列",
      "fileSize": 456,
      "mimeType": "レスポンス文字列",
      "createdAt": "レスポンス文字列"
    }
  ],
  "groups": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "レスポンス文字列"
    }
  ],
  "createdAt": "レスポンス文字列",
  "updatedAt": "レスポンス文字列",
  "lastUsedAt": "レスポンス文字列",
  "canUpdate": false,
  "canDelete": false
}
```

***

### スキルの削除 <a href="#skills-destroy" id="skills-destroy"></a>

DELETE `/api/v1/skills/{id}/`

#### パラメータ

| パラメータ名 | 必須 | 型      | 説明                                    |
| ------ | -- | ------ | ------------------------------------- |
| `id`   | ✅  | string | A UUID string identifying this Skill. |

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出しの例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定します
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// リクエストボディ (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->delete("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンスボディ

| ステータスコード | 説明               |
| -------- | ---------------- |
| 204      | No response body |

***

### スキルのエクスポート <a href="#skills-export-retrieve" id="skills-export-retrieve"></a>

GET `/api/v1/skills/{id}/export/`

#### パラメータ

| パラメータ名 | 必須 | 型      | 説明                                    |
| ------ | -- | ------ | ------------------------------------- |
| `id`   | ✅  | string | A UUID string identifying this Skill. |

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出しの例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/export/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定します
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/export/", config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/export/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/export/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンス内容

| ステータスコード | 説明                 |
| -------- | ------------------ |
| 200      | .skill ファイルのダウンロード |

***

### スキルパッケージのディレクトリ構造の参照 <a href="#skills-package-structure-retrieve" id="skills-package-structure-retrieve"></a>

GET `/api/v1/skills/{id}/package-structure/`

#### パラメータ

| パラメータ名 | 必須 | 型      | 説明                                    |
| ------ | -- | ------ | ------------------------------------- |
| `id`   | ✅  | string | A UUID string identifying this Skill. |
| `path` | ❌  | string | 参照するディレクトリのパス（デフォルトはルートディレクトリです）      |

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/package-structure/?path=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定します
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/package-structure/?path=example", config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/package-structure/?path=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/package-structure/?path=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンス内容

**ステータスコード: 200**

**レスポンススキーマの例**

```typescript
{
  "package_name"?: string // スキルパッケージのファイル名 (任意)
  "package_size"?: integer // スキルパッケージのサイズ（bytes） (任意)
  "uploaded_at"?: string (date-time) // アップロード日時 (任意)
  "current_path"?: string // 現在参照しているパス (任意)
  "items"?: [ // ディレクトリの内容（フォルダを先に表示し、アルファベット順に並べます） (任意)
    {
      "name"?: string // ファイルまたはフォルダの名前 (任意)
      "type"?: string (enum: file, dir) // 項目の種類 (任意)
      "size"?: integer // ファイルサイズ（bytes）です。type=file の場合のみ返されます (任意)
      "item_count"?: integer // フォルダ直下の子項目数です。type=dir の場合のみ返されます (任意)
    }
  ]
}
```

**レスポンス値の例**

```json
{
  "package_name": "レスポンス文字列",
  "package_size": 456,
  "uploaded_at": "2025-01-01T00:00:00.000Z",
  "current_path": "レスポンス文字列",
  "items": [
    {
      "name": "レスポンス文字列",
      "type": "file",
      "size": 456,
      "item_count": 456
    }
  ]
}
```

**ステータスコード: 400**

**レスポンススキーマの例**

```typescript
{
  "detail"?: string // エラーメッセージ (任意)
}
```

**レスポンス値の例**

```json
{
  "detail": "レスポンス文字列"
}
```

***

### スキルの再アップロード <a href="#skills-reupload-create" id="skills-reupload-create"></a>

POST `/api/v1/skills/{id}/reupload/`

#### パラメータ

| パラメータ名 | 必須 | 型      | 説明                                    |
| ------ | -- | ------ | ------------------------------------- |
| `id`   | ✅  | string | A UUID string identifying this Skill. |

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出し例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/reupload/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -F "file=@example_file.pdf"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');
const FormData = require('form-data');

// FormData オブジェクトを作成します
const formData = new FormData();
// 実際のファイルに置き換えてください
formData.append('file', /* 実際のファイルオブジェクト */, 'example_file.pdf');

// リクエストヘッダーを設定します
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    ...formData.getHeaders()
  }
};

axios.post("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/reupload/", formData, config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/reupload/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}

# ファイルとフォームデータを用意します
files = {
    'file': ('example_file.pdf', open('example_file.pdf', 'rb'), 'application/pdf')
}

response = requests.post(url, files=files, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/skills/550e8400-e29b-41d4-a716-446655440000/reupload/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ],
        'multipart' => [
            [
                'name' => 'file',
                'contents' => fopen('example_file.pdf', 'r'),
                'filename' => 'example_file.pdf'
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンス内容

**ステータスコード: 200**

**レスポンススキーマの例**

```typescript
{
  "id"?: string (uuid) // 任意
  "name"?: string // 任意
  "description"?: string // 任意
  "message"?: string // 任意
}
```

**レスポンス値の例**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "レスポンス文字列",
  "description": "レスポンス文字列",
  "message": "レスポンス文字列"
}
```

**ステータスコード: 400**

**レスポンススキーマの例**

```typescript
{
  "detail"?: string // エラーメッセージ (任意)
}
```

**レスポンス値の例**

```json
{
  "detail": "レスポンス文字列"
}
```

***

### スキルリソースの一覧取得 <a href="#skills-resources-list" id="skills-resources-list"></a>

GET `/api/v1/skills/{skillPk}/resources/`

#### パラメータ

| パラメータ名    | 必須 | 型      | 説明 |
| --------- | -- | ------ | -- |
| `skillPk` | ✅  | string |    |

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定します
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/", config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンス内容

**ステータスコード: 200**

**レスポンススキーマの例**

```typescript
[
  {
    "id": string (uuid)
    "path": string // Relative path within the skill directory, e.g. scripts/helper.py
    "filePath": string // S3 path: skills/{organization_id}/{skill_id}/resources/
    "fileSize": integer // File size in bytes
    "mimeType": string
    "createdAt": string (timestamp)
  }
]
```

**レスポンス値の例**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "path": "レスポンス文字列",
    "filePath": "レスポンス文字列",
    "fileSize": 456,
    "mimeType": "レスポンス文字列",
    "createdAt": "レスポンス文字列"
  }
]
```

***

### スキルリソースのアップロード <a href="#skills-resources-create" id="skills-resources-create"></a>

POST `/api/v1/skills/{skillPk}/resources/`

#### パラメータ

| パラメータ名    | 必須 | 型      | 説明 |
| --------- | -- | ------ | -- |
| `skillPk` | ✅  | string |    |

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出し例 (Shell)
curl -X POST "https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -F "file=@example_file.pdf" \
  -F "path=サンプル文字列"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');
const FormData = require('form-data');

// FormData オブジェクトを作成します
const formData = new FormData();
// 実際のファイルに置き換えてください
formData.append('file', /* 実際のファイルオブジェクト */, 'example_file.pdf');
formData.append('path', 'サンプル文字列');

// リクエストヘッダーを設定します
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    ...formData.getHeaders()
  }
};

axios.post("https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/", formData, config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}

# ファイルとフォームデータを用意します
files = {
    'file': ('example_file.pdf', open('example_file.pdf', 'rb'), 'application/pdf'),
    'path': (None, 'サンプル文字列')
}

response = requests.post(url, files=files, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->post("https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ],
        'multipart' => [
            [
                'name' => 'file',
                'contents' => fopen('example_file.pdf', 'r'),
                'filename' => 'example_file.pdf'
            ],
            [
                'name' => 'path',
                'contents' => 'サンプル文字列'
            ]
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンス内容

**ステータスコード: 201**

**レスポンススキーマの例**

```typescript
{
  "id": string (uuid)
  "path": string // Relative path within the skill directory, e.g. scripts/helper.py
  "filePath": string // S3 path: skills/{organization_id}/{skill_id}/resources/
  "fileSize": integer // File size in bytes
  "mimeType": string
  "createdAt": string (timestamp)
}
```

**レスポンス値の例**

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "path": "レスポンス文字列",
  "filePath": "レスポンス文字列",
  "fileSize": 456,
  "mimeType": "レスポンス文字列",
  "createdAt": "レスポンス文字列"
}
```

**ステータスコード: 400**

**レスポンススキーマの例**

```typescript
{
  "path"?: string // パスの検証エラー (任意)
  "file"?: string // ファイルの検証エラー (任意)
}
```

**レスポンス値の例**

```json
{
  "path": "レスポンス文字列",
  "file": "レスポンス文字列"
}
```

***

### スキルリソースの削除 <a href="#skills-resources-destroy" id="skills-resources-destroy"></a>

DELETE `/api/v1/skills/{skillPk}/resources/{id}/`

#### パラメータ

| パラメータ名    | 必須 | 型      | 説明 |
| --------- | -- | ------ | -- |
| `id`      | ✅  | string |    |
| `skillPk` | ✅  | string |    |

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出し例 (Shell)
curl -X DELETE "https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定します
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

// リクエスト内容 (payload)
const data = null;

axios.delete("https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/550e8400-e29b-41d4-a716-446655440000/", data, config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.delete(url, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->delete("https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンス内容

| ステータスコード | 説明               |
| -------- | ---------------- |
| 204      | No response body |

***

### スキルリソースのダウンロード <a href="#skills-resources-download-retrieve" id="skills-resources-download-retrieve"></a>

GET `/api/v1/skills/{skillPk}/resources/{id}/download/`

#### パラメータ

| パラメータ名    | 必須 | 型      | 説明 |
| --------- | -- | ------ | -- |
| `id`      | ✅  | string |    |
| `skillPk` | ✅  | string |    |

#### コード例

{% tabs %}
{% tab title="Shell/Bash" %}

```bash
# API 呼び出し例 (Shell)
curl -X GET "https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/550e8400-e29b-41d4-a716-446655440000/download/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# 実行前に YOUR_API_KEY を置き換え、リクエストデータを確認してください。
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const axios = require('axios');

// リクエストヘッダーを設定します
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/550e8400-e29b-41d4-a716-446655440000/download/", config)
  .then(response => {
    console.log('レスポンスを正常に取得しました:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('リクエストでエラーが発生しました:');
    console.error(error.response?.data || error.message);
  });
```

{% endtab %}

{% tab title="Python" %}

```python
import requests

url = "https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/550e8400-e29b-41d4-a716-446655440000/download/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("レスポンスを正常に取得しました:")
    print(response.json())
except Exception as e:
    print("リクエストでエラーが発生しました:", e)
```

{% endtab %}

{% tab title="PHP" %}

```php
<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/v1/skills/{skillPk}/resources/550e8400-e29b-41d4-a716-446655440000/download/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "レスポンスを正常に取得しました:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'リクエストでエラーが発生しました: ' . $e->getMessage();
}
?>
```

{% endtab %}
{% endtabs %}

#### レスポンス内容

| ステータスコード | 説明          |
| -------- | ----------- |
| 200      | ファイルのダウンロード |

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/api/ja/api-reference/ji-neng.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.