Agent: Skills

Overview

The Agent Skills endpoints manage the agent’s skill library: listing installed skills, searching and installing from the remote skill hub, previewing and importing skills, reading and writing skill source, and toggling trust/enable state. Skills are scoped to the requesting cwd/config_dir and are realm-scoped to the gateway’s own realm — a client-supplied X-Hoody-Realm or ?realm= is ignored when the gateway has its own pinned/active realm.

All endpoints accept the standard per-request scope headers (X-Hoody-Cwd, X-Hoody-Config-Dir, X-Hoody-Container, X-Hoody-Realm) and the ?realm= query alias.

Listing and cache

`GET /api/v1/agent/skills`

Lists the installed skills (identity = root + rel) for the requesting cwd/config_dir, with their enabled/trust state. Realm-scoped to the gateway’s own realm.

Parameters

Name	In	Type	Required	Description
`page`	query	integer	No	1-based page number for pagination.
`limit`	query	integer	No	Maximum items per page (`0` = no pagination).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex id.
`realm`	query	string	No	Query alias of `X-Hoody-Realm` (read only when the header is absent).

Response

{
  "items": [
    {
      "root": "project",
      "rel": "skills/commit",
      "name": "commit",
      "enabled": true,
      "trusted": true
    }
  ],
  "meta": {
    "total": 12,
    "page": 1,
    "limit": 50
  }
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

SDK usage

await client.agent.skills.listSkillsIterator({ page: 1, limit: 50 })

cURL

curl "https://5f3a9b2e8d1c4e7f0a2b6d8c-4c1d8e9f3a5b7c2e1d8f6a4b-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/skills?page=1&limit=50"

`GET /api/v1/agent/skills/hub/cache`

Returns the skill-hub fetch cache statistics (skills.cache_stats).

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex id.
`realm`	query	string	No	Query alias of `X-Hoody-Realm` (read only when the header is absent).

Response

{
  "entries": 23,
  "bytes": 184320,
  "hits": 142,
  "misses": 17,
  "pinned": 4
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK usage

await client.agent.skills.getSkillHubCache()

cURL

curl "https://5f3a9b2e8d1c4e7f0a2b6d8c-4c1d8e9f3a5b7c2e1d8f6a4b-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/skills/hub/cache"

Hub search and preview

`GET /api/v1/agent/skills/hub/search`

Searches the remote skill hub (skills.hub_search). Pass ?q= in the query.

Parameters

Name	In	Type	Required	Description
`q`	query	string	No	Search query.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex id.
`realm`	query	string	No	Query alias of `X-Hoody-Realm` (read only when the header is absent).

Response

{
  "results": [
    {
      "id": "hub/commit-format",
      "name": "commit-format",
      "description": "Conventional commit helper",
      "version": "1.2.0",
      "author": "hoody"
    }
  ],
  "total": 1
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK usage

await client.agent.skills.searchSkillHub({ q: "commit format" })

cURL

curl "https://5f3a9b2e8d1c4e7f0a2b6d8c-4c1d8e9f3a5b7c2e1d8f6a4b-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/skills/hub/search?q=commit%20format"

`GET /api/v1/agent/skills/hub/preview`

Fetches a preview of a hub skill before install (skills.hub_preview). Pass ?id= to identify the hub skill.

Parameters

Name	In	Type	Required	Description
`id`	query	string	No	Hub skill identifier.
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex id.
`realm`	query	string	No	Query alias of `X-Hoody-Realm` (read only when the header is absent).

Response

{
  "id": "hub/commit-format",
  "name": "commit-format",
  "version": "1.2.0",
  "readme": "# commit-format\n\nFormats conventional commits.",
  "permissions": ["network.read"]
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK usage

await client.agent.skills.previewSkillHub({ id: "hub/commit-format" })

cURL

curl "https://5f3a9b2e8d1c4e7f0a2b6d8c-4c1d8e9f3a5b7c2e1d8f6a4b-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/skills/hub/preview?id=hub%2Fcommit-format"

Skill source

`GET /api/v1/agent/skills/source`

Returns a skill’s source body (skills.read_source). Identify the skill by the daemon keys root_dir + rel_dir (the friendly aliases ?root= / ?rel= are also accepted and translated). The reply is {content, gen, path}; pass gen back as base_gen on the write to detect conflicts.

Parameters

Name	In	Type	Required	Description
`root_dir`	query	string	No	Skill root directory (identity; alias: `root`).
`rel_dir`	query	string	No	Skill relative directory (identity; alias: `rel`).
`root`	query	string	No	Friendly alias of `root_dir` (translated to `root_dir` server-side).
`rel`	query	string	No	Friendly alias of `rel_dir` (translated to `rel_dir` server-side).
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex id.
`realm`	query	string	No	Query alias of `X-Hoody-Realm` (read only when the header is absent).

Response

{
  "content": "# commit\n\nWrites a conventional commit message.",
  "gen": 3,
  "path": "/home/user/.hoody/project/skills/commit/SKILL.md"
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK usage

await client.agent.skills.getSkillSource({ root_dir: "project", rel_dir: "skills/commit" })

cURL

curl "https://5f3a9b2e8d1c4e7f0a2b6d8c-4c1d8e9f3a5b7c2e1d8f6a4b-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/skills/source?root_dir=project&rel_dir=skills%2Fcommit"

`PUT /api/v1/agent/skills/source`

Overwrites a skill’s source body (skills.write_source). Identify the skill by root_dir + rel_dir in the body (aliases root / rel accepted); the new body text is content (alias source); pass the read’s gen as base_gen for conflict detection.

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex id.
`realm`	query	string	No	Query alias of `X-Hoody-Realm` (read only when the header is absent).

Request Body

Name	Type	Required	Description
`root_dir`	string	Yes	Skill root directory (identity; alias: `root`).
`rel_dir`	string	Yes	Skill relative directory (identity; alias: `rel`).
`content`	string	Yes	New `SKILL.md` body (alias: `source`).
`base_gen`	integer	No	The `gen` returned by `skills.read_source`, for conflict detection.

Response

{
  "ok": true,
  "gen": 4,
  "path": "/home/user/.hoody/project/skills/commit/SKILL.md"
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`). The gateway rejects an oversized body at the edge before the handler reads it.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK usage

await client.agent.skills.putSkillSource({
  root_dir: "project",
  rel_dir: "skills/commit",
  content: "# commit\n\nWrites a conventional commit message.",
  base_gen: 3
})

cURL

curl -X PUT "https://5f3a9b2e8d1c4e7f0a2b6d8c-4c1d8e9f3a5b7c2e1d8f6a4b-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/skills/source" \
  -H "Content-Type: application/json" \
  -d '{
    "root_dir": "project",
    "rel_dir": "skills/commit",
    "content": "# commit\n\nWrites a conventional commit message.",
    "base_gen": 3
  }'

Skill imports

`GET /api/v1/agent/skills/import/scan`

Scans well-known locations for importable skills (skills.import_scan).

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex id.
`realm`	query	string	No	Query alias of `X-Hoody-Realm` (read only when the header is absent).

Response

{
  "found": [
    {
      "path": "/opt/shared/skills/release-notes",
      "name": "release-notes",
      "source": "shared"
    }
  ],
  "scanned": 4
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK usage

await client.agent.skills.scanSkillImport()

cURL

curl "https://5f3a9b2e8d1c4e7f0a2b6d8c-4c1d8e9f3a5b7c2e1d8f6a4b-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/skills/import/scan"

`POST /api/v1/agent/skills/import/apply`

Imports a discovered skill into the local store (skills.import_apply).

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex id.
`realm`	query	string	No	Query alias of `X-Hoody-Realm` (read only when the header is absent).

Request Body

The body is forwarded to the daemon skills.import_apply RPC. Identify the discovered skill to import (e.g. by its scan path/id returned from scanSkillImport). Reserved _-prefixed keys are ignored and the request scope (cwd/config_dir) is applied automatically.

Response

{
  "ok": true,
  "imported": "release-notes",
  "path": "/home/user/.hoody/project/skills/release-notes"
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`). The gateway rejects an oversized body at the edge before the handler reads it.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK usage

await client.agent.skills.applySkillImport({ path: "/opt/shared/skills/release-notes" })

cURL

curl -X POST "https://5f3a9b2e8d1c4e7f0a2b6d8c-4c1d8e9f3a5b7c2e1d8f6a4b-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/skills/import/apply" \
  -H "Content-Type: application/json" \
  -d '{ "path": "/opt/shared/skills/release-notes" }'

Skill CRUD

`POST /api/v1/agent/skills`

Creates a new local skill (skills.create).

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex id.
`realm`	query	string	No	Query alias of `X-Hoody-Realm` (read only when the header is absent).

Request Body

Name	Type	Required	Description
`name`	string	Yes	Skill name (the `SKILL.md` directory stem).
`description`	string	No	Skill description (frontmatter).
`content`	string	No	Initial `SKILL.md` body.

Response

{
  "ok": true,
  "name": "review",
  "path": "/home/user/.hoody/project/skills/review/SKILL.md"
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`). The gateway rejects an oversized body at the edge before the handler reads it.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK usage

await client.agent.skills.createSkill({
  name: "review",
  description: "Generates a code review summary",
  content: "# review\n\nGenerates a code review summary."
})

cURL

curl -X POST "https://5f3a9b2e8d1c4e7f0a2b6d8c-4c1d8e9f3a5b7c2e1d8f6a4b-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/skills" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "review",
    "description": "Generates a code review summary",
    "content": "# review\n\nGenerates a code review summary."
  }'

`POST /api/v1/agent/skills/delete`

Deletes a skill (skills.delete). Identify the skill by root_dir + rel_dir in the body (aliases root / rel accepted).

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex id.
`realm`	query	string	No	Query alias of `X-Hoody-Realm` (read only when the header is absent).

Request Body

Name	Type	Required	Description
`root_dir`	string	Yes	Skill root directory (identity; alias: `root`).
`rel_dir`	string	Yes	Skill relative directory (identity; alias: `rel`).

Response

{
  "ok": true,
  "deleted": "review"
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`). The gateway rejects an oversized body at the edge before the handler reads it.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK usage

await client.agent.skills.deleteSkill({ root_dir: "project", rel_dir: "skills/review" })

cURL

curl -X POST "https://5f3a9b2e8d1c4e7f0a2b6d8c-4c1d8e9f3a5b7c2e1d8f6a4b-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/skills/delete" \
  -H "Content-Type: application/json" \
  -d '{ "root_dir": "project", "rel_dir": "skills/review" }'

`POST /api/v1/agent/skills/rename`

Renames a skill (skills.rename). Identify the skill by root_dir + rel_dir (aliases root / rel accepted) and pass the new name as new_name.

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex id.
`realm`	query	string	No	Query alias of `X-Hoody-Realm` (read only when the header is absent).

Request Body

Name	Type	Required	Description
`root_dir`	string	Yes	Skill root directory (identity; alias: `root`).
`rel_dir`	string	Yes	Skill relative directory (identity; alias: `rel`).
`new_name`	string	Yes	New skill directory name.

Response

{
  "ok": true,
  "old_name": "review",
  "new_name": "code-review"
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`). The gateway rejects an oversized body at the edge before the handler reads it.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK usage

await client.agent.skills.renameSkill({
  root_dir: "project",
  rel_dir: "skills/review",
  new_name: "code-review"
})

cURL

curl -X POST "https://5f3a9b2e8d1c4e7f0a2b6d8c-4c1d8e9f3a5b7c2e1d8f6a4b-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/skills/rename" \
  -H "Content-Type: application/json" \
  -d '{ "root_dir": "project", "rel_dir": "skills/review", "new_name": "code-review" }'

Skill state

`POST /api/v1/agent/skills/toggle`

Toggles a skill’s enabled state (skills.toggle — NAME-scoped: it gates the effective skill name in the runtime registry). Identify the skill by name in the body, and pass disabled (boolean) for the new state.

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex id.
`realm`	query	string	No	Query alias of `X-Hoody-Realm` (read only when the header is absent).

Request Body

Name	Type	Required	Description
`name`	string	Yes	Effective skill name (NOT `root`/`rel` — toggle is name-scoped).
`disabled`	boolean	No	`true` to disable the skill, `false` to enable it.

Response

{
  "ok": true,
  "name": "commit",
  "disabled": true
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`). The gateway rejects an oversized body at the edge before the handler reads it.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK usage

await client.agent.skills.toggleSkill({ name: "commit", disabled: true })

cURL

curl -X POST "https://5f3a9b2e8d1c4e7f0a2b6d8c-4c1d8e9f3a5b7c2e1d8f6a4b-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/skills/toggle" \
  -H "Content-Type: application/json" \
  -d '{ "name": "commit", "disabled": true }'

`POST /api/v1/agent/skills/trust`

Sets a skill’s trust state (skills.set_trust). Identify the skill by root_dir + rel_dir (aliases root / rel accepted); the trust flag is trusted (boolean). Trust gates arbitrary code execution.

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex id.
`realm`	query	string	No	Query alias of `X-Hoody-Realm` (read only when the header is absent).

Request Body

Name	Type	Required	Description
`root_dir`	string	Yes	Skill root directory (identity; alias: `root`).
`rel_dir`	string	Yes	Skill relative directory (identity; alias: `rel`).
`trusted`	boolean	Yes	`true` to grant execution trust, `false` to revoke.

Response

{
  "ok": true,
  "trusted": true
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`). The gateway rejects an oversized body at the edge before the handler reads it.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK usage

await client.agent.skills.trustSkill({
  root_dir: "project",
  rel_dir: "skills/commit",
  trusted: true
})

cURL

curl -X POST "https://5f3a9b2e8d1c4e7f0a2b6d8c-4c1d8e9f3a5b7c2e1d8f6a4b-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/skills/trust" \
  -H "Content-Type: application/json" \
  -d '{ "root_dir": "project", "rel_dir": "skills/commit", "trusted": true }'

Hub install and cache

`POST /api/v1/agent/skills/hub/install`

Installs a skill from the hub (skills.hub_install) — this writes arbitrary skill code to disk.

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex id.
`realm`	query	string	No	Query alias of `X-Hoody-Realm` (read only when the header is absent).

Request Body

Name	Type	Required	Description
`id`	string	Yes	Hub skill identifier (from `searchSkillHub` / `previewSkillHub`).

Response

{
  "ok": true,
  "installed": "commit-format",
  "path": "/home/user/.hoody/project/skills/commit-format",
  "trusted": false
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "payload_too_large",
  "message": "request body exceeds the configured size limit"
}

Error Code	Title	Description	Resolution
`payload_too_large`	Payload too large	The request body exceeds the configured size cap (`MaxBodyBytes`). The gateway rejects an oversized body at the edge before the handler reads it.	Reduce the request body below the configured limit (default 8 MiB); split a large payload into smaller requests.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK usage

await client.agent.skills.installSkillHub({ id: "hub/commit-format" })

cURL

curl -X POST "https://5f3a9b2e8d1c4e7f0a2b6d8c-4c1d8e9f3a5b7c2e1d8f6a4b-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/skills/hub/install" \
  -H "Content-Type: application/json" \
  -d '{ "id": "hub/commit-format" }'

`DELETE /api/v1/agent/skills/hub/cache`

Clears the skill-hub fetch cache, including pins (skills.cache_clear).

Parameters

Name	In	Type	Required	Description
`X-Hoody-Cwd`	header	string	No	Per-request working-directory scope.
`X-Hoody-Config-Dir`	header	string	No	Per-request `--config-dir` override.
`X-Hoody-Container`	header	string	No	Per-request bound remote container (omitted = local).
`X-Hoody-Realm`	header	string	No	Per-request realm selector: `"global"` or a 24-hex id.
`realm`	query	string	No	Query alias of `X-Hoody-Realm` (read only when the header is absent).

Response

{
  "ok": true,
  "cleared": 23,
  "pins_cleared": 4
}

{
  "code": "bad_request",
  "message": "invalid request"
}

Error Code	Title	Description	Resolution
`bad_request`	Bad request	The request was malformed or carried invalid parameters.	Correct the request body or query parameters.
`realm_scope_unsupported`	Realm scope unsupported	A per-request realm header was supplied to an active-only / global-no-realm RPC, which has no realm dimension to scope.	Omit the realm header on this route, or open a session to scope by realm.

{
  "code": "forbidden",
  "message": "request must arrive through the Hoody proxy"
}

Error Code	Title	Description	Resolution
`forbidden`	Forbidden (not via the Hoody proxy)	The request did not reach the service through the public endpoint.	Reach the agent through `hoody-proxy` (e.g. `hoody agent …` → platform → proxy), not by connecting to the container directly.

{
  "code": "not_found",
  "message": "resource not found"
}

Error Code	Title	Description	Resolution
`not_found`	Not found	The requested resource does not exist.	Verify the path and identifier.

{
  "code": "rate_limited",
  "message": "request rate limit exceeded"
}

Error Code	Title	Description	Resolution
`rate_limited`	Too many requests	The per-client request rate limit was exceeded; the gateway throttled the request before dispatch.	Honor the `Retry-After` header and retry; reduce the request rate.

{
  "code": "internal_error",
  "message": "internal server error"
}

Error Code	Title	Description	Resolution
`internal_error`	Internal error	An unexpected error occurred while handling the request.	Retry; if persistent, inspect the daemon logs.

{
  "code": "service_unavailable",
  "message": "service unavailable"
}

Error Code	Title	Description	Resolution
`service_unavailable`	Service unavailable	The daemon could not service the request (too busy, or a per-client stream concurrency cap was hit).	Honor `Retry-After` and retry.

SDK usage

await client.agent.skills.clearSkillHubCache()

cURL

curl -X DELETE "https://5f3a9b2e8d1c4e7f0a2b6d8c-4c1d8e9f3a5b7c2e1d8f6a4b-agent-1.us-east-1.containers.hoody.icu/api/v1/agent/skills/hub/cache"