# API Reference: Skills

## GET `/skills/`

**Summary:** List Skills

**Description:** List all skills accessible to the user (via File System).

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `feature` | query | No | anyOf | Filter skills by feature (e.g., 'swarm_control', 'voice_chat') |
| `x-user-id` | header | No | anyOf |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/skills/?feature=<feature>' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>'
```

---

## POST `/skills/`

**Summary:** Create Skill

**Description:** Create a new skill folder on the physical filesystem.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `x-user-id` | header | No | anyOf |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `SkillCreate` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/skills/' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## PUT `/skills/{skill_id}`

**Summary:** Update Skill

**Description:** Update top level metadata of an FS skill (emoji and system flag).

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `skill_id` | path | Yes | string |  |
| `x-user-id` | header | No | anyOf |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `SkillUpdate` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'PUT' \
  'http://localhost:8000/api/v1/skills/{skill_id}' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## DELETE `/skills/{skill_id}`

**Summary:** Delete Skill

**Description:** Delete a skill permanently via shutil.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `skill_id` | path | Yes | string |  |
| `x-user-id` | header | No | anyOf |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'DELETE' \
  'http://localhost:8000/api/v1/skills/{skill_id}' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>'
```

---

## GET `/skills/{skill_id}/files`

**Summary:** List Skill Files

**Description:** Get file tree for a skill.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `skill_id` | path | Yes | string |  |
| `x-user-id` | header | No | anyOf |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/skills/{skill_id}/files' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>'
```

---

## GET `/skills/{skill_id}/files/{path}`

**Summary:** Read Skill File

**Description:** Read a specific skill file.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `skill_id` | path | Yes | string |  |
| `path` | path | Yes | string |  |
| `x-user-id` | header | No | anyOf |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'GET' \
  'http://localhost:8000/api/v1/skills/{skill_id}/files/{path}' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>'
```

---

## POST `/skills/{skill_id}/files/{path}`

**Summary:** Create Or Update Skill File

**Description:** Create or update a skill file.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `skill_id` | path | Yes | string |  |
| `path` | path | Yes | string |  |
| `x-user-id` | header | No | anyOf |  |

#### Request Body

**Required:** Yes

- **Media Type:** `application/json`
- **Schema:** `SkillFileUpdate` (Define in Models)

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'POST' \
  'http://localhost:8000/api/v1/skills/{skill_id}/files/{path}' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

---

## DELETE `/skills/{skill_id}/files/{path}`

**Summary:** Delete Skill File

**Description:** Delete a skill file literally from disk.

#### Parameters

| Name | In | Required | Type | Description |
|------|----|----------|------|-------------|
| `skill_id` | path | Yes | string |  |
| `path` | path | Yes | string |  |
| `x-user-id` | header | No | anyOf |  |

#### Responses

| Status Code | Description |
|-------------|-------------|
| `200` | Successful Response |
| `422` | Validation Error |

#### Example Usage

```bash
curl -X 'DELETE' \
  'http://localhost:8000/api/v1/skills/{skill_id}/files/{path}' \
  -H 'accept: application/json' \
  -H 'X-User-ID: <your_user_id>'
```

---

