Skip to content
Hoody Documentation
Download Page (.md)

The Agent Skills API provides comprehensive management of skills across the Hoody platform: browse and install from the hub, create and manage local skills, import from external locations, read and write source bodies, and control runtime state via enable/disable and trust flags. Use these endpoints when building tooling that operates on the skill registry for a given working directory.

List skills

Section titled “List skills”

GET /api/v1/agent/skills

Section titled “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 (pinned or active); a client-supplied X-Hoody-Realm / ?realm= is ignored.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
pagequeryintegerNo1-based page number for pagination.
limitqueryintegerNoMaximum items per page (0 = no pagination).
X-Hoody-CwdheaderstringNoPer-request working-directory scope (§6.1): the .hoody project layer / record cwd / tool+workflow cwd.
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override (§6.1).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (§6.1; omitted = local).
X-Hoody-RealmheaderstringNoPer-request realm selector (§6.1): "global" or a 24-hex id (also accepted as ?realm=).
realmquerystringNoQuery alias of the X-Hoody-Realm header.

SDK

Section titled “SDK”
await client.agent.skills.listSkillsIterator({ page: 1, limit: 50 });

Response

Section titled “Response”
{
  "items": [
    {
      "root": "user",
      "rel": "skills/data-viz",
      "name": "data-viz",
      "description": "Render charts from tabular data.",
      "enabled": true,
      "trusted": false,
      "origin": "local"
    },
    {
      "root": "project",
      "rel": "skills/release-notes",
      "name": "release-notes",
      "description": "Draft release notes from a git log.",
      "enabled": true,
      "trusted": true,
      "origin": "hub"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "limit": 50
  }
}

Skill hub

Section titled “Skill hub”

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

Section titled “GET /api/v1/agent/skills/hub/search”

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

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
qquerystringNoSearch query.
X-Hoody-CwdheaderstringNoPer-request working-directory scope (§6.1).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override (§6.1).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (§6.1; omitted = local).
X-Hoody-RealmheaderstringNoPer-request realm selector (§6.1).
realmquerystringNoQuery alias of the X-Hoody-Realm header.

SDK

Section titled “SDK”
await client.agent.skills.searchSkillHub({ q: "kubernetes deploy" });

Response

Section titled “Response”
{
  "results": [
    {
      "id": "k8s-deploy-blueprint",
      "name": "k8s-deploy-blueprint",
      "description": "Scaffold Kubernetes deployments from a service spec.",
      "author": "hoody",
      "version": "1.4.0"
    }
  ],
  "total": 1
}

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

Section titled “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

Section titled “Parameters”
NameInTypeRequiredDescription
idquerystringNoHub skill identifier.
X-Hoody-CwdheaderstringNoPer-request working-directory scope (§6.1).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override (§6.1).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (§6.1; omitted = local).
X-Hoody-RealmheaderstringNoPer-request realm selector (§6.1).
realmquerystringNoQuery alias of the X-Hoody-Realm header.

SDK

Section titled “SDK”
await client.agent.skills.previewSkillHub({ id: "k8s-deploy-blueprint" });

Response

Section titled “Response”
{
  "id": "k8s-deploy-blueprint",
  "name": "k8s-deploy-blueprint",
  "description": "Scaffold Kubernetes deployments from a service spec.",
  "version": "1.4.0",
  "readme": "# k8s-deploy-blueprint\n\nGenerates manifests, kustomize overlays, and a rollout plan.",
  "files": [
    { "path": "SKILL.md", "size": 1450 },
    { "path": "templates/deployment.yaml", "size": 612 }
  ]
}

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

Section titled “POST /api/v1/agent/skills/hub/install”

Installs a skill from the hub (skills.hub_install). This writes arbitrary skill code to disk. The daemon’s human-only _machine_confirmed denial lives only on the model-facing tool path, not on the skills.hub_install RPC this route dispatches.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope (§6.1).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override (§6.1).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (§6.1; omitted = local).
X-Hoody-RealmheaderstringNoPer-request realm selector (§6.1).
realmquerystringNoQuery alias of the X-Hoody-Realm header.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
idstringYesHub skill identifier (from searchSkillHub / previewSkillHub).

SDK

Section titled “SDK”
await client.agent.skills.installSkillHub({ id: "k8s-deploy-blueprint" });

Response

Section titled “Response”
{
  "ok": true,
  "id": "k8s-deploy-blueprint",
  "root": "user",
  "rel": "skills/k8s-deploy-blueprint",
  "trusted": false
}

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

Section titled “GET /api/v1/agent/skills/hub/cache”

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

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope (§6.1).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override (§6.1).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (§6.1; omitted = local).
X-Hoody-RealmheaderstringNoPer-request realm selector (§6.1).
realmquerystringNoQuery alias of the X-Hoody-Realm header.

SDK

Section titled “SDK”
await client.agent.skills.getSkillHubCache();

Response

Section titled “Response”
{
  "entries": 12,
  "bytes": 184320,
  "hits": 47,
  "misses": 9,
  "pinned": 2
}

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

Section titled “DELETE /api/v1/agent/skills/hub/cache”

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

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope (§6.1).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override (§6.1).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (§6.1; omitted = local).
X-Hoody-RealmheaderstringNoPer-request realm selector (§6.1).
realmquerystringNoQuery alias of the X-Hoody-Realm header.

SDK

Section titled “SDK”
await client.agent.skills.clearSkillHubCache();

Response

Section titled “Response”
{
  "ok": true,
  "cleared_entries": 12,
  "cleared_pins": 2
}

Skill import

Section titled “Skill import”

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

Section titled “GET /api/v1/agent/skills/import/scan”

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

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope (§6.1).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override (§6.1).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (§6.1; omitted = local).
X-Hoody-RealmheaderstringNoPer-request realm selector (§6.1).
realmquerystringNoQuery alias of the X-Hoody-Realm header.

SDK

Section titled “SDK”
await client.agent.skills.scanSkillImport();

Response

Section titled “Response”
{
  "candidates": [
    {
      "path": "/home/user/.legacy-skills/old-notebook",
      "name": "old-notebook",
      "has_skill_md": true,
      "size_bytes": 8421
    }
  ]
}

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

Section titled “POST /api/v1/agent/skills/import/apply”

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

The request body is forwarded verbatim to the daemon RPC (the gateway scrubs every _-prefixed key and folds in the request scope). Identify the discovered skill to import using the fields returned by scanSkillImport (e.g. its scan path/id).

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope (§6.1).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override (§6.1).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (§6.1; omitted = local).
X-Hoody-RealmheaderstringNoPer-request realm selector (§6.1).
realmquerystringNoQuery alias of the X-Hoody-Realm header.

Request Body

Section titled “Request Body”

The body schema is open (additionalProperties: true); the gateway passes through every non-_-prefixed key to skills.import_apply. Use the keys the daemon RPC reads — for example, the scan path or candidate id returned by scanSkillImport.

SDK

Section titled “SDK”
await client.agent.skills.applySkillImport({ path: "/home/user/.legacy-skills/old-notebook" });

Response

Section titled “Response”
{
  "ok": true,
  "root": "user",
  "rel": "skills/old-notebook",
  "name": "old-notebook"
}

Skill source

Section titled “Skill source”

GET /api/v1/agent/skills/source

Section titled “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 in the query (the friendly aliases ?root= / ?rel= are also accepted and translated). Returns {content, gen, path}; pass gen back as base_gen on the write to detect conflicts.

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
root_dirquerystringNoSkill root directory (identity; alias: root).
rel_dirquerystringNoSkill relative directory (identity; alias: rel).
rootquerystringNoFriendly alias of root_dir (translated server-side).
relquerystringNoFriendly alias of rel_dir (translated server-side).
X-Hoody-CwdheaderstringNoPer-request working-directory scope (§6.1).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override (§6.1).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (§6.1; omitted = local).
X-Hoody-RealmheaderstringNoPer-request realm selector (§6.1).
realmquerystringNoQuery alias of the X-Hoody-Realm header.

SDK

Section titled “SDK”
await client.agent.skills.getSkillSource({ root_dir: "user", rel_dir: "skills/data-viz" });

Response

Section titled “Response”
{
  "content": "# data-viz\n\nRender charts from tabular data using the local chart-renderer tool.\n",
  "gen": 7,
  "path": "user/skills/data-viz/SKILL.md"
}

PUT /api/v1/agent/skills/source

Section titled “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

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope (§6.1).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override (§6.1).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (§6.1; omitted = local).
X-Hoody-RealmheaderstringNoPer-request realm selector (§6.1).
realmquerystringNoQuery alias of the X-Hoody-Realm header.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
root_dirstringYesSkill root directory (identity; alias: root).
rel_dirstringYesSkill relative directory (identity; alias: rel).
contentstringYesNew SKILL.md body (alias: source).
base_genintegerNoThe gen returned by skills.read_source, for conflict detection.

SDK

Section titled “SDK”
await client.agent.skills.putSkillSource({
  root_dir: "user",
  rel_dir: "skills/data-viz",
  content: "# data-viz\n\nUpdated chart-renderer docs.\n",
  base_gen: 7,
});

Response

Section titled “Response”
{
  "ok": true,
  "gen": 8,
  "path": "user/skills/data-viz/SKILL.md"
}

Skill CRUD

Section titled “Skill CRUD”

POST /api/v1/agent/skills

Section titled “POST /api/v1/agent/skills”

Creates a new local skill (skills.create).

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope (§6.1).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override (§6.1).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (§6.1; omitted = local).
X-Hoody-RealmheaderstringNoPer-request realm selector (§6.1).
realmquerystringNoQuery alias of the X-Hoody-Realm header.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
namestringYesSkill name (the SKILL.md directory stem).
descriptionstringNoSkill description (frontmatter).
contentstringNoInitial SKILL.md body.

SDK

Section titled “SDK”
await client.agent.skills.createSkill({
  name: "release-notes",
  description: "Draft release notes from a git log.",
  content: "# release-notes\n\nSummarize a git log range.\n",
});

Response

Section titled “Response”
{
  "ok": true,
  "root": "user",
  "rel": "skills/release-notes",
  "name": "release-notes"
}

POST /api/v1/agent/skills/delete

Section titled “POST /api/v1/agent/skills/delete”

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

Parameters

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope (§6.1).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override (§6.1).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (§6.1; omitted = local).
X-Hoody-RealmheaderstringNoPer-request realm selector (§6.1).
realmquerystringNoQuery alias of the X-Hoody-Realm header.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
root_dirstringYesSkill root directory (identity; alias: root).
rel_dirstringYesSkill relative directory (identity; alias: rel).

SDK

Section titled “SDK”
await client.agent.skills.deleteSkill({ root_dir: "user", rel_dir: "skills/old-notebook" });

Response

Section titled “Response”
{
  "ok": true,
  "root": "user",
  "rel": "skills/old-notebook"
}

POST /api/v1/agent/skills/rename

Section titled “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

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope (§6.1).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override (§6.1).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (§6.1; omitted = local).
X-Hoody-RealmheaderstringNoPer-request realm selector (§6.1).
realmquerystringNoQuery alias of the X-Hoody-Realm header.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
root_dirstringYesSkill root directory (identity; alias: root).
rel_dirstringYesSkill relative directory (identity; alias: rel).
new_namestringYesNew skill directory name.

SDK

Section titled “SDK”
await client.agent.skills.renameSkill({
  root_dir: "user",
  rel_dir: "skills/release-notes",
  new_name: "changelog",
});

Response

Section titled “Response”
{
  "ok": true,
  "root": "user",
  "rel": "skills/changelog",
  "old_rel": "skills/release-notes"
}

Skill state

Section titled “Skill state”

POST /api/v1/agent/skills/toggle

Section titled “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

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope (§6.1).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override (§6.1).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (§6.1; omitted = local).
X-Hoody-RealmheaderstringNoPer-request realm selector (§6.1).
realmquerystringNoQuery alias of the X-Hoody-Realm header.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
namestringYesEffective skill name (not root/rel — toggle is name-scoped).
disabledbooleanNotrue to disable the skill, false to enable it.

SDK

Section titled “SDK”
await client.agent.skills.toggleSkill({ name: "data-viz", disabled: true });

Response

Section titled “Response”
{
  "ok": true,
  "name": "data-viz",
  "disabled": true
}

POST /api/v1/agent/skills/trust

Section titled “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

Section titled “Parameters”
NameInTypeRequiredDescription
X-Hoody-CwdheaderstringNoPer-request working-directory scope (§6.1).
X-Hoody-Config-DirheaderstringNoPer-request --config-dir override (§6.1).
X-Hoody-ContainerheaderstringNoPer-request bound remote container (§6.1; omitted = local).
X-Hoody-RealmheaderstringNoPer-request realm selector (§6.1).
realmquerystringNoQuery alias of the X-Hoody-Realm header.

Request Body

Section titled “Request Body”
NameTypeRequiredDescription
root_dirstringYesSkill root directory (identity; alias: root).
rel_dirstringYesSkill relative directory (identity; alias: rel).
trustedbooleanYestrue to grant execution trust, false to revoke.

SDK

Section titled “SDK”
await client.agent.skills.trustSkill({
  root_dir: "user",
  rel_dir: "skills/data-viz",
  trusted: true,
});

Response

Section titled “Response”
{
  "ok": true,
  "root": "user",
  "rel": "skills/data-viz",
  "trusted": true
}