Managing skills via the API

The Skills API lets you author custom skills as plain SKILL.md files (plus optional helper scripts) and push them straight to your agents. No GitHub repo, no manifest file, no dashboard click-through. The same workflow that works from Claude Code works from a CI job, a curl one-liner, or any HTTP client.

This is the programmatic alternative to the dashboard's "Custom" install path described in Creating Custom Skills. The dashboard expects a public GitHub URL; the API takes the file content directly.

If your skill already lives in a public GitHub repo with a manifest.json, you can install it straight from the URL instead. See Installing a GitHub skill via the API.

Two steps, not one

The most common mistake when first using this API is assuming POST /v1/skills puts the skill on an agent. It does not. Uploading a skill and installing it on an agent are two separate calls.

• POST /v1/skills uploads the skill to your account's catalog. After this call, the skill exists at the account level but no agent has it yet. It will not show up in any agent's Extensions tab.
• POST /v1/agents/:id/skills then installs that skill on a specific agent. Run it once per agent you want the skill on.
• POST /v1/agents/:id/restart (or a UI restart) loads the files into the running container.

If you skip step two, the skill is stored but never reaches any agent. The dashboard's Extensions tab only shows installed skills, not catalog entries, so a freshly uploaded but uninstalled skill will look like nothing happened.

Lifecycle at a glance

1. Upload the skill to your account's catalog with POST /v1/skills. Returns a skillId. The skill is now stored at the account level. It is not yet on any agent.
2. Install it on one or more agents with POST /v1/agents/:id/skills. Run this once per agent you want the skill on. Each call is independent: installing on agent A does nothing for agent B.
3. Restart each agent so the new files load into the container.
4. Update the skill with PATCH /v1/skills/custom/:id whenever you iterate.
5. Restart affected agents again.
6. Uninstall from a single agent with DELETE /v1/agents/:id/skills/:skillId, or delete the skill entirely (and remove it from every agent at once) with DELETE /v1/skills/custom/:id.

All endpoints require an API key with the skills scope. Mint one at agento.host/app/api-keys.

Body shape

The request body is a small JSON object. The only required files entry is SKILL.md; everything else is optional helper content.

{
  "name": "my-trello-helper",
  "description": "Manage Trello boards, lists, and cards.",
  "version": "1.0.0",
  "files": {
    "SKILL.md": "---\nname: my-trello-helper\ndescription: Manage Trello via REST.\n---\n\n# Trello\n\nUse `$TRELLO_API_KEY` and `$TRELLO_TOKEN`.\n",
    "scripts/list-cards.sh": "#!/bin/bash\ncurl -s \"https://api.trello.com/1/boards/$1/cards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN\"\n"
  }
}

Field rules:

Field	Notes
name	Lowercase letters, digits, hyphens. 1 to 64 chars. Must match SKILL.md frontmatter name.
description	1 to 500 chars.
version	Semver (e.g. 1.0.0). Required on POST. On PATCH the patch number auto-bumps if you omit it.
kind	Optional. Defaults to openclaw. hermes is reserved and not yet supported.
files	Object map of relative paths to UTF-8 content. Must include SKILL.md.

Limits:

• 256 KB per file, 1 MB total per skill.
• File extensions allowed: .md, .json, .sh, .py, .js, .ts, .txt, .yaml, .yml, .toml.
• 25 custom skills per account by default. Higher plans get more.
• Path safety: no .., no leading /, no backslashes. Segments must be [a-zA-Z0-9._-].

Worked example

Create the skill:

curl -s https://api.agento.host/v1/skills \
  -H "X-Api-Key: $AGENTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @skill.json

Response (the skillId is what you install):

{
  "data": {
    "skillId": "sk_my-trello-helper-9f8a2c1b",
    "name": "my-trello-helper",
    "description": "Manage Trello boards, lists, and cards.",
    "version": "1.0.0",
    "kind": "openclaw",
    "fileCount": 2,
    "totalSizeBytes": 384,
    "createdAt": "2026-05-02T12:00:00.000Z",
    "updatedAt": "2026-05-02T12:00:00.000Z"
  }
}

Install on an agent:

curl -s https://api.agento.host/v1/agents/$AGENT_ID/skills \
  -H "X-Api-Key: $AGENTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "skillId": "sk_my-trello-helper-9f8a2c1b", "trustLevel": "custom" }'

Restart the agent:

curl -s -X POST https://api.agento.host/v1/agents/$AGENT_ID/restart \
  -H "X-Api-Key: $AGENTO_API_KEY"

Iterate. After tweaking SKILL.md, push the new content. The patch number auto-bumps because version was omitted:

curl -s -X PATCH https://api.agento.host/v1/skills/custom/sk_my-trello-helper-9f8a2c1b \
  -H "X-Api-Key: $AGENTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "files": { "SKILL.md": "---\nname: my-trello-helper\ndescription: Manage Trello via REST.\n---\n\n# Trello\n\nNew instructions here.\n" } }'

The response includes needsRestart: true and affectedAgentCount: 1. Restart the agent to pick up the new version.

Bundling a folder into JSON

The body shape is a JSON object with a files map. If you keep your skill as a folder on disk, this 30-line bash helper turns it into a request body. Save it as bundle-skill.sh, chmod +x, and pipe its output to curl.

#!/usr/bin/env bash
set -euo pipefail

# Usage: bundle-skill.sh <skill-folder> <name> <description> <version>
DIR="${1:-.}"
NAME="${2:?name required}"
DESCRIPTION="${3:?description required}"
VERSION="${4:?version required}"

cd "$DIR"
[ -f SKILL.md ] || { echo "SKILL.md not found in $DIR" >&2; exit 1; }

# Build the files map. Walk the directory, skip dotfiles, encode each file.
files_json=$(
  find . -type f -not -path '*/.*' \
    | sed 's|^\./||' \
    | jq -R -s -c --rawfile _ /dev/stdin '
        split("\n")
        | map(select(length > 0))
        | map({ key: ., value: (input_filename|tojson) })
      ' /dev/null > /dev/null 2>&1 || true

  printf '{'
  first=1
  while IFS= read -r path; do
    [ "$first" -eq 1 ] || printf ','
    first=0
    printf '%s:%s' "$(printf '%s' "$path" | jq -R)" "$(jq -Rs . < "$path")"
  done < <(find . -type f -not -path '*/.*' | sed 's|^\./||')
  printf '}'
)

jq -n \
  --arg name "$NAME" \
  --arg description "$DESCRIPTION" \
  --arg version "$VERSION" \
  --argjson files "$files_json" \
  '{ name: $name, description: $description, version: $version, files: $files }'

Then:

./bundle-skill.sh ./my-skill my-trello-helper "Manage Trello via REST." 1.0.0 \
  | curl -s https://api.agento.host/v1/skills \
      -H "X-Api-Key: $AGENTO_API_KEY" \
      -H "Content-Type: application/json" \
      -d @-

Download a copy: bundle-skill.sh.

Versioning rules

• version is semver, supplied by you on create. Use whatever convention fits your workflow.
• On PATCH you can pass a new version, or omit it to auto-bump the patch number (1.0.0 becomes 1.0.1).
• Downgrades (e.g. 2.0.0 to 1.5.0) are allowed but logged. Most users will never hit this.
• Agents persist the installed version. After updating a skill, agents that have it installed must be restarted to pick up the new content. The orchestrator detects the version change via an on-disk .version marker and re-syncs the files.

Multi-agent install

A custom skill belongs to your account, not a single agent. Install the same skillId on as many agents as you like:

for AGENT in $AGENT_A $AGENT_B $AGENT_C; do
  curl -s https://api.agento.host/v1/agents/$AGENT/skills \
    -H "X-Api-Key: $AGENTO_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{ \"skillId\": \"sk_my-trello-helper-9f8a2c1b\", \"trustLevel\": \"custom\" }"
done

When you PATCH the skill, every agent that has it installed gets flagged for restart. Restart each one to roll out the new version.

Listing and inspecting

# All custom skills you've authored.
curl -s https://api.agento.host/v1/skills/custom \
  -H "X-Api-Key: $AGENTO_API_KEY"

# One skill, with file list and the agents it's installed on.
curl -s https://api.agento.host/v1/skills/custom/sk_my-trello-helper-9f8a2c1b \
  -H "X-Api-Key: $AGENTO_API_KEY"

# A specific file, returned as raw text — useful for round-tripping back to your editor.
curl -s https://api.agento.host/v1/skills/custom/sk_my-trello-helper-9f8a2c1b/files/SKILL.md \
  -H "X-Api-Key: $AGENTO_API_KEY"

Deleting

If the skill is not installed on any agent, DELETE works directly:

curl -s -X DELETE https://api.agento.host/v1/skills/custom/sk_my-trello-helper-9f8a2c1b \
  -H "X-Api-Key: $AGENTO_API_KEY"

If it is installed somewhere, the API returns 409 conflict. Pass ?force=true to cascade-uninstall and delete in one call:

curl -s -X DELETE "https://api.agento.host/v1/skills/custom/sk_my-trello-helper-9f8a2c1b?force=true" \
  -H "X-Api-Key: $AGENTO_API_KEY"

Differences from the dashboard "Custom" flow

	Dashboard	API
Source	Public GitHub URL	Inline files in the request body
Manifest	Requires openclaw.plugin.json in the repo	Built from request fields, no manifest needed
Iteration	Push to GitHub, click "Reinstall"	PATCH and restart
Multi-file	Yes (whatever's in the repo)	Yes (up to 1 MB total)
Best for	Skills you also want to share publicly	Personal or account-private skills, fast iteration

Both flows produce the same on-disk extension layout inside the agent container, so OpenClaw treats them identically once installed.

Pointing Claude Code at this guide

The full Skills API surface is in the OpenAPI spec at api.agento.host/openapi.json, and the LLM-friendly flat reference at api.agento.host/llms-full.txt. Drop either into a Claude Code conversation along with this guide and ask it to author a skill end-to-end. See the Using the Public API guide for more on driving the API from an LLM.