Skills
Create, update and delete workspace skills from SKILL.md or a .zip bundle, choose which agents load them, and publish them to Explore.
On this page
A skill is reusable know-how in a SKILL.md file: when to use it, the steps, and anything an agent must never do. Agents read each skill’s description and load the skill when it matches the task. A skill can include scripts and reference files alongside SKILL.md. In prompts and system prompts, skills are referenced as #name. See Skills for the file format.
The skill object
| Field | Type | Description |
|---|---|---|
id | string | Unique id, prefixed skl_. |
object | string | Always "skill". |
name | string | Lowercase letters, digits and dashes, e.g. stripe-webhooks. Unique in the workspace. |
description | string | What agents read to decide when to load the skill. |
body | string | The SKILL.md instructions as Markdown, without front matter. |
files | object[] | Extra files from a bundle: path and size in bytes. Empty for single-file skills. |
agents | string[] | Agent names that may load it. Empty means every agent. |
visibility | enum | private, team, workspace, link or public (listed on Explore). |
version | string | null | The latest published version, e.g. 1.2.0. null if never published. |
created_at | string | When the skill was created. |
updated_at | string | When it last changed. |
{
"id": "skl_stripewh",
"object": "skill",
"name": "stripe-webhooks",
"description": "Handling Stripe webhook events safely: signature checks, idempotency and replay.",
"body": "# Stripe webhooks\n\n## When to use\nAny change to code that receives Stripe events.\n\n## Steps\n1. Verify the signature before parsing.\n2. Dedupe on the event id.\n3. Post money movements through LedgerGuard.post().\n",
"files": [
{ "path": "scripts/replay-event.sh", "size": 1840 },
{ "path": "references/event-types.md", "size": 6213 }
],
"agents": [],
"visibility": "workspace",
"version": "1.2.0",
"created_at": "2026-10-03T09:00:00Z",
"updated_at": "2026-11-12T15:44:10Z"
}Endpoints
List skills
https://api.duun.ai/v1/skills Returns workspace skills by name, including ones installed from Explore. Needs skills:read.
Query parameters
-
agentstring Optional -
Only skills this agent may load (including skills open to every agent).
-
visibilityenum Optional -
Only skills with this visibility.
-
limitinteger Optional -
1–100.
-
cursorstring Optional -
next_cursorfrom the previous page.
curl "https://api.duun.ai/v1/skills?agent=builder" \
-H "Authorization: Bearer $DUUN_API_KEY"import Duun from "@duun/sdk";
const duun = new Duun({ apiKey: process.env.DUUN_API_KEY });
for await (const skill of duun.skills.list({ agent: "builder" })) {
console.log(`#${skill.name}`, skill.description);
}from duun import Duun
client = Duun()
for skill in client.skills.list(agent="builder"):
print(f"#{skill.name}", skill.description){
"object": "list",
"data": [
{ "id": "skl_payments", "object": "skill", "name": "payments", "description": "Stripe, ledger invariants, reconciliation", "agents": [], "visibility": "workspace", "version": null },
{ "id": "skl_stripewh", "object": "skill", "name": "stripe-webhooks", "description": "Handling Stripe webhook events safely: signature checks, idempotency and replay.", "agents": [], "visibility": "workspace", "version": "1.2.0" }
],
"has_more": false,
"next_cursor": null
}List items are full skill objects, including body; the example is trimmed.
Create a skill
https://api.duun.ai/v1/skills Adds a workspace skill. Send JSON for a single SKILL.md, or multipart/form-data with a .zip bundle that contains SKILL.md at its root plus scripts and references. In a bundle, name and description come from the SKILL.md front matter unless you also send them as form fields. Needs skills:write.
Body parameters
-
namestring Required -
Lowercase letters, digits and dashes. Required for JSON requests.
-
descriptionstring Required -
What agents read to decide when to load it. Required for JSON requests.
-
bodystring Optional -
The instructions as Markdown. Required for JSON requests.
-
bundlefile Optional -
Multipart only: a
.zipup to 10 MB withSKILL.mdat its root. -
agentsstring[] Optional -
Agent names that may load it. Omit or send an empty list for every agent.
-
visibilityenum Optional -
Who in the workspace can see and use it. To share outside the workspace, publish it.
# Single SKILL.md as JSON
curl https://api.duun.ai/v1/skills \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "postgres-migrations",
"description": "Safe Postgres migrations: locks, EXPLAIN reading, backfills.",
"body": "# Postgres\n\nNever take an ACCESS EXCLUSIVE lock on a hot table."
}'
# Bundle with scripts and references
curl https://api.duun.ai/v1/skills \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-F [email protected]import fs from "node:fs";
const skill = await duun.skills.create({
name: "postgres-migrations",
description: "Safe Postgres migrations: locks, EXPLAIN reading, backfills.",
body: fs.readFileSync("skills/postgres-migrations/SKILL.md", "utf8"),
});
// Or upload a bundle
const bundled = await duun.skills.create({ bundle: fs.createReadStream("stripe-webhooks.zip") });from pathlib import Path
skill = client.skills.create(
name="postgres-migrations",
description="Safe Postgres migrations: locks, EXPLAIN reading, backfills.",
body=Path("skills/postgres-migrations/SKILL.md").read_text(),
)
# Or upload a bundle
bundled = client.skills.create(bundle=open("stripe-webhooks.zip", "rb")){
"id": "skl_pgmig41",
"object": "skill",
"name": "postgres-migrations",
"description": "Safe Postgres migrations: locks, EXPLAIN reading, backfills.",
"body": "# Postgres\n\nNever take an ACCESS EXCLUSIVE lock on a hot table.",
"files": [],
"agents": [],
"visibility": "workspace",
"version": null,
"created_at": "2026-11-15T11:30:00Z",
"updated_at": "2026-11-15T11:30:00Z"
}Errors worth handling:
409 conflictwith codename_taken: update the existing skill instead.400 invalid_requestwith codebundle_invalidwhen the zip has noSKILL.mdat its root or its front matter is missingnameordescription.
Retrieve a skill
https://api.duun.ai/v1/skills/{skill} Returns one skill. You can pass its id or its name. Needs skills:read.
Path parameters
-
skillstring Required -
The skill's id (
skl_stripewh) or name (stripe-webhooks).
curl https://api.duun.ai/v1/skills/stripe-webhooks \
-H "Authorization: Bearer $DUUN_API_KEY"const skill = await duun.skills.retrieve("stripe-webhooks");skill = client.skills.retrieve("stripe-webhooks")The response is a skill object.
Update a skill
https://api.duun.ai/v1/skills/{skill} Changes a skill. Send only the fields you want to change, or a new bundle as multipart to replace the files. Agents use the new version from their next step. If the skill is published, the published listing doesn’t change until you publish again. Needs skills:write.
Path parameters
-
skillstring Required -
The skill's id or name.
Body parameters
-
namestring Optional -
Renaming changes the
#nameagents and prompts use. -
descriptionstring Optional -
What agents read to decide when to load it.
-
bodystring Optional -
The instructions as Markdown.
-
bundlefile Optional -
Multipart only: replaces
bodyand every file. -
agentsstring[] Optional -
Replaces the list. Empty means every agent.
-
visibilityenum Optional -
Visibility inside the workspace.
curl -X PATCH https://api.duun.ai/v1/skills/stripe-webhooks \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "agents": ["builder", "reviewer"] }'await duun.skills.update("stripe-webhooks", { agents: ["builder", "reviewer"] });client.skills.update("stripe-webhooks", agents=["builder", "reviewer"]){
"id": "skl_stripewh",
"object": "skill",
"name": "stripe-webhooks",
"agents": ["builder", "reviewer"],
"updated_at": "2026-11-15T11:34:12Z"
}The response is the full skill object; the example is trimmed.
Delete a skill
https://api.duun.ai/v1/skills/{skill} Deletes a workspace skill. Agents stop loading it from their next step. If it’s published, it’s also unpublished; workspaces that installed it keep their copy. Needs skills:write.
Path parameters
-
skillstring Required -
The skill's id or name.
curl -X DELETE https://api.duun.ai/v1/skills/postgres-migrations \
-H "Authorization: Bearer $DUUN_API_KEY"await duun.skills.delete("postgres-migrations");client.skills.delete("postgres-migrations"){ "id": "skl_pgmig41", "object": "skill", "deleted": true }Publish a skill
https://api.duun.ai/v1/skills/{skill}/publish Publishes the skill’s current content as a new version, for your team, your workspace, anyone with the link, or everyone on Explore. Publishing runs the same preflight as Publish to Explore… in the app: secret values, repo names, machine ids, webhook URLs and Slack channels are stripped to placeholders, and connectors the skill relies on become requirements. Needs skills:write.
Path parameters
-
skillstring Required -
The skill's id or name.
Body parameters
-
visibilityenum Required -
linkisn't listed; anyone with the link can view and install.publicis listed on Explore for every Duun workspace. -
versionstring Optional -
Semantic version. Defaults to
1.0.0for the first publish; after that it's required and must be higher than the last one. -
release_notesstring Optional -
What changed. Required for every version after the first.
-
teamsstring[] Optional -
Team names, when
visibilityisteam.
curl https://api.duun.ai/v1/skills/stripe-webhooks/publish \
-H "Authorization: Bearer $DUUN_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"visibility": "public",
"version": "1.3.0",
"release_notes": "Adds a replay script and covers out-of-order delivery."
}'const publication = await duun.skills.publish("stripe-webhooks", {
visibility: "public",
version: "1.3.0",
release_notes: "Adds a replay script and covers out-of-order delivery.",
});
console.log(publication.item_url);publication = client.skills.publish(
"stripe-webhooks",
visibility="public",
version="1.3.0",
release_notes="Adds a replay script and covers out-of-order delivery.",
)
print(publication.item_url){
"object": "publication",
"id": "pub_6Lw0sK",
"item_url": "https://app.duun.ai/explore/skill/stripe-webhooks",
"visibility": "public",
"version": "1.3.0",
"state": "live",
"preflight": [
{ "ref": "STRIPE_TEST_KEY", "class": "stripped", "note": "Secret value replaced with a placeholder; installers are asked for their own." },
{ "ref": "stripe", "class": "becomes_requirement", "note": "Installers need the Stripe integration connected." }
]
}Errors worth handling:
422 validation_errorwith codepreflight_blockedwhen the skill references something you don’t own. Theproblemsname each item.422 validation_errorwith codelisting_incompleteforpublic: the skill needs a description and at least one example in its body.409 conflictwith codeversion_existswhenversionisn’t higher than the last published version.
Related
- Skills (SKILL.md) and Publishing to Explore
duun skills pushandduun skills publish- Publish to Explore in the help center