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