# Agent: Skills

**Page:** api/agent/skills

[Download Raw Markdown](./api/agent/skills.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## Agent: Skills

Manage agent skills within a workspace: browse the public marketplace, create, read, update, and delete custom skills, and toggle built-in skills on or off. Skills are reusable instructions that the agent can invoke via `exec_user_script`; this page documents the CRUD and discovery operations that back that workflow.

---

### `GET /api/v1/exec-skills`

Returns the ground truth list of scripts available to the agent via `exec_user_script`.



```json
{
  "all": ["git-status", "run-tests", "lint-code"],
  "agent": ["git-status", "lint-code"]
}
```


Hoody Exec service unavailable.

```json
{
  "error": "Service Unavailable",
  "message": "Hoody Exec service is currently unavailable"
}
```





```bash
curl -X GET https://api.hoody.com/api/v1/exec-skills \
  -H "Authorization: Bearer <token>"
```


```ts
const scripts = await client.agent.skills.discover();
```



---

### `GET /api/v1/workspaces/{workspaceID}/skills/marketplace`

Browse skills from the `skillsmp.com` marketplace. Results are cached for 5 minutes.

This endpoint takes a path parameter.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier. |



```json
{
  "skills": [
    {
      "name": "code-review-assistant",
      "description": "Performs a structured code review on a pull request.",
      "author": "skillsmp",
      "tags": ["review", "quality"],
      "downloads": 12453
    },
    {
      "name": "sql-query-builder",
      "description": "Builds safe, parameterized SQL queries from natural language.",
      "author": "skillsmp",
      "tags": ["database", "sql"],
      "downloads": 8912
    }
  ],
  "total": 2
}
```





```bash
curl -X GET https://api.hoody.com/api/v1/workspaces/ws_8f3a1b/skills/marketplace \
  -H "Authorization: Bearer <token>"
```


```ts
const marketplace = await client.agent.skills.listMarketplace({
  workspaceID: "ws_8f3a1b"
});
```



---

### `GET /api/v1/workspaces/{workspaceID}/skills/{name}`

Get a skill by name with its full content.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier. |
| `name` | path | string | Yes | The name of the skill. |



```json
{
  "name": "code-review",
  "description": "Reviews staged changes and reports potential issues.",
  "location": "/workspaces/ws_8f3a1b/skills/code-review/SKILL.md",
  "content": "# Code Review\n\nReview the diff and summarize findings by severity.",
  "scope": "project",
  "editable": true,
  "enabled": true,
  "builtin": false
}
```





```bash
curl -X GET https://api.hoody.com/api/v1/workspaces/ws_8f3a1b/skills/code-review \
  -H "Authorization: Bearer <token>"
```


```ts
const skill = await client.agent.skills.get({
  workspaceID: "ws_8f3a1b",
  name: "code-review"
});
```



---

### `PUT /api/v1/workspaces/{workspaceID}/skills/{name}`

Create a new skill or update an existing one. `scope` is only used on create; changing a skill's scope requires deleting and recreating it.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier. |
| `name` | path | string | Yes | The name of the skill. |

#### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `description` | string | Yes | A human-readable description of what the skill does. |
| `content` | string | Yes | The skill body (typically Markdown instructions). |
| `scope` | string | No | The skill scope. One of `project` or `global`. Default: `"project"`. |
| `enabled` | boolean | No | Whether the skill is enabled. |

```json
{
  "description": "Reviews staged changes and reports potential issues.",
  "content": "# Code Review\n\nReview the diff and summarize findings by severity.",
  "scope": "project",
  "enabled": true
}
```



```json
{
  "name": "code-review",
  "description": "Reviews staged changes and reports potential issues.",
  "location": "/workspaces/ws_8f3a1b/skills/code-review/SKILL.md",
  "content": "# Code Review\n\nReview the diff and summarize findings by severity.",
  "scope": "project",
  "editable": true,
  "enabled": true,
  "builtin": false
}
```


```json
{
  "name": "code-review",
  "description": "Reviews staged changes and reports potential issues.",
  "location": "/workspaces/ws_8f3a1b/skills/code-review/SKILL.md",
  "content": "# Code Review\n\nReview the diff and summarize findings by severity.",
  "scope": "project",
  "editable": true,
  "enabled": true,
  "builtin": false
}
```


```json
{
  "data": null,
  "errors": [
    {
      "propertyNames": ["content"],
      "message": "content must not be empty"
    }
  ],
  "success": false
}
```


Skill is read-only.

```json
{
  "error": "Forbidden",
  "message": "Built-in skills cannot be modified"
}
```


Skill already exists.

```json
{
  "error": "Conflict",
  "message": "A skill with this name already exists; use PATCH to update it"
}
```





```bash
curl -X PUT https://api.hoody.com/api/v1/workspaces/ws_8f3a1b/skills/code-review \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Reviews staged changes and reports potential issues.",
    "content": "# Code Review\n\nReview the diff and summarize findings by severity.",
    "scope": "project",
    "enabled": true
  }'
```


```ts
const skill = await client.agent.skills.upsert({
  workspaceID: "ws_8f3a1b",
  name: "code-review",
  data: {
    description: "Reviews staged changes and reports potential issues.",
    content: "# Code Review\n\nReview the diff and summarize findings by severity.",
    scope: "project",
    enabled: true
  }
});
```



---

### `PATCH /api/v1/workspaces/{workspaceID}/skills/{name}`

Partially update an existing skill. At least one of `description` or `content` must be provided.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier. |
| `name` | path | string | Yes | The name of the skill. |

#### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `description` | string | No | A human-readable description of what the skill does. |
| `content` | string | No | The skill body (typically Markdown instructions). |
| `enabled` | boolean | No | Whether the skill is enabled. |

```json
{
  "description": "Reviews staged changes and reports potential issues, with severity grouping.",
  "enabled": false
}
```



```json
{
  "name": "code-review",
  "description": "Reviews staged changes and reports potential issues, with severity grouping.",
  "location": "/workspaces/ws_8f3a1b/skills/code-review/SKILL.md",
  "content": "# Code Review\n\nReview the diff and summarize findings by severity.",
  "scope": "project",
  "editable": true,
  "enabled": false,
  "builtin": false
}
```


```json
{
  "data": null,
  "errors": [
    {
      "propertyNames": ["body"],
      "message": "At least one of description or content must be provided"
    }
  ],
  "success": false
}
```


Skill is read-only.

```json
{
  "error": "Forbidden",
  "message": "Built-in skills cannot be modified"
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Skill 'code-review' not found in workspace ws_8f3a1b"
  }
}
```





```bash
curl -X PATCH https://api.hoody.com/api/v1/workspaces/ws_8f3a1b/skills/code-review \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Reviews staged changes and reports potential issues, with severity grouping.",
    "enabled": false
  }'
```


```ts
const skill = await client.agent.skills.update({
  workspaceID: "ws_8f3a1b",
  name: "code-review",
  data: {
    description: "Reviews staged changes and reports potential issues, with severity grouping.",
    enabled: false
  }
});
```



---

### `PATCH /api/v1/workspaces/{workspaceID}/skills/builtin/{name}`

Enable or disable a built-in skill.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier. |
| `name` | path | string | Yes | The name of the built-in skill. |

#### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `enabled` | boolean | Yes | Whether the built-in skill should be enabled. |

```json
{
  "enabled": true
}
```



```json
{
  "name": "web-search",
  "description": "Performs a web search and summarizes the top results.",
  "location": "/builtin/skills/web-search/SKILL.md",
  "content": "# Web Search\n\nUse web_search to find current information.",
  "scope": "project",
  "editable": false,
  "enabled": true,
  "builtin": true
}
```


```json
{
  "data": null,
  "errors": [
    {
      "propertyNames": ["enabled"],
      "message": "enabled must be a boolean"
    }
  ],
  "success": false
}
```


Not a built-in skill.

```json
{
  "error": "Not Found",
  "message": "'code-review' is not a built-in skill"
}
```





```bash
curl -X PATCH https://api.hoody.com/api/v1/workspaces/ws_8f3a1b/skills/builtin/web-search \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true
  }'
```


```ts
const skill = await client.agent.skills.toggleBuiltin({
  workspaceID: "ws_8f3a1b",
  name: "web-search",
  data: {
    enabled: true
  }
});
```



---

### `DELETE /api/v1/workspaces/{workspaceID}/skills/{name}`

Delete an editable skill by name.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | The workspace identifier. |
| `name` | path | string | Yes | The name of the skill. |



```json
{
  "success": true
}
```


```json
{
  "data": null,
  "errors": [
    {
      "propertyNames": ["name"],
      "message": "name must not be empty"
    }
  ],
  "success": false
}
```


Skill is read-only.

```json
{
  "error": "Forbidden",
  "message": "Built-in skills cannot be deleted"
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Skill 'code-review' not found in workspace ws_8f3a1b"
  }
}
```





```bash
curl -X DELETE https://api.hoody.com/api/v1/workspaces/ws_8f3a1b/skills/code-review \
  -H "Authorization: Bearer <token>"
```


```ts
const result = await client.agent.skills.delete({
  workspaceID: "ws_8f3a1b",
  name: "code-review"
});
```




Built-in skills cannot be modified or deleted with the standard CRUD endpoints. Use the dedicated `toggleBuiltin` endpoint to enable or disable a built-in skill for a workspace.