Adds or revises one of the caller org's own skills, and answers 201 with the…
Adds or revises one of the caller org's own skills, and answers 201 with the stored record.
POST /v1/tools/skills
| Address | https://api.hanzo.ai/v1/tools/skills |
| Method | POST |
| Operation | post_tools_skills |
| Auth | Authorization: Bearer $HANZO_API_KEY |
Adds or revises one of the caller org's own skills, and answers 201 with the stored record. The id is derived from the name, so writing the same name again REVISES that skill rather than accumulating near-duplicates that would then collide in the registry. An org's skills are private to it by construction — they live in a different store from the brand's embedded catalogue and have no path into the public gallery — and a brand skill always wins a name collision against an org's.
Request
3 fields, body application/json (required).
| Field | In | Type | Required | Description |
|---|---|---|---|---|
content | body | string | — | Content is the SKILL.md body. |
description | body | string | — | Description is the one-line summary discovery shows for the skill. |
name | body | string | — | Name is the skill's id within the org: one lowercase path segment (a-z0-9, _ or -). |
Response
| Status | Body | Meaning |
|---|---|---|
201 | skillWritten | created |
201 body — 7 fields.
| Field | In | Type | Always | Description |
|---|---|---|---|---|
skill | body | Skill | — | |
skill.content | body | string | — | Content is the SKILL.md body, markdown. |
skill.createdAt | body | integer | — | CreatedAt is when the skill was last written, Unix seconds. |
skill.description | body | string | — | Description is the one-line summary discovery shows for the skill. |
skill.id | body | string | — | ID is the skill's id within the org. |
skill.name | body | string | — | Name is the skill's name: one lowercase path segment (a-z0-9, _ or -). |
skill.org | body | string | — | Org is the org that authored the skill — the validated caller's, never a value the body supplied. |
Failure carries the platform error shape — see Errors.
Examples
hanzo has no subcommand for this operation — the CLI serves only what cloud's live route table confirms. Use HTTP or an SDK.
import { Configuration, ToolsApi } from 'hanzoai';
const api = new ToolsApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postToolsSkills({ content: "<content>", description: "<description>" });from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import ToolsApi
client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = ToolsApi(client).post_tools_skills(content="<content>", description="<description>")cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)
resp, _, err := client.ToolsAPI.PostToolsSkills(context.Background()).Execute()
if err != nil {
return err
}use hanzo_cloud::apis::{configuration::Configuration, tools_api};
let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();
let result = tools_api::post_tools_skills(&cfg, Default::default()).await?;import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.ToolsApi;
ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));
var result = new ToolsApi(client).postToolsSkills();The method above is the one at the current release of the document. [email protected] (npm) and [email protected] (PyPI) were generated from an earlier release, where this operation carried a different id, so it spells the method differently — regenerating the clients is what makes the two agree. SDKs →
curl -X POST https://api.hanzo.ai/v1/tools/skills \
-H "Authorization: Bearer $HANZO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "<content>",
"description": "<description>"
}'The door reaches tools through the tools tool, which names its 19 operations with its own verbs — this one among them, under a name only the door declares. describe explains any of them:
curl -X POST https://api.hanzo.ai/v1/mcp \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "describe",
"arguments": {
"op": "list_mcp_servers"
}
}
}'How is this guide?