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.

Response 200

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

Response 503

Hoody Exec service unavailable.

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

cURL

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

SDK

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.

Response 200

{
  "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
}

cURL

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

SDK

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.

Response 200

{
  "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
}

cURL

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

SDK

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.

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

Response 200

{
  "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
}

Response 201

{
  "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
}

Response 400

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

Response 403

Skill is read-only.

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

Response 409

Skill already exists.

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

cURL

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
  }'

SDK

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.

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

Response 200

{
  "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
}

Response 400

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

Response 403

Skill is read-only.

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

Response 404

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

cURL

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
  }'

SDK

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.

{
  "enabled": true
}

Response 200

{
  "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
}

Response 400

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

Response 404

Not a built-in skill.

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

cURL

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
  }'

SDK

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.

Response 200

{
  "success": true
}

Response 400

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

Response 403

Skill is read-only.

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

Response 404

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

cURL

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

SDK

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

Note

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.