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

FieldTypeDescription
idstringUnique id, prefixed skl_.
objectstringAlways "skill".
namestringLowercase letters, digits and dashes, e.g. stripe-webhooks. Unique in the workspace.
descriptionstringWhat agents read to decide when to load the skill.
bodystringThe SKILL.md instructions as Markdown, without front matter.
filesobject[]Extra files from a bundle: path and size in bytes. Empty for single-file skills.
agentsstring[]Agent names that may load it. Empty means every agent.
visibilityenumprivate, team, workspace, link or public (listed on Explore).
versionstring | nullThe latest published version, e.g. 1.2.0. null if never published.
created_atstringWhen the skill was created.
updated_atstringWhen it last changed.
Skill
{
  "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

GET https://api.duun.ai/v1/skills

Returns workspace skills by name, including ones installed from Explore. Needs skills:read.

Query parameters

agent string Optional

Only skills this agent may load (including skills open to every agent).

visibility enum Optional

Only skills with this visibility.

One of private team workspace link public

limit integer Optional

1–100.

Default 20

cursor string Optional

next_cursor from 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)
Response
{
  "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

POST 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

name string Required

Lowercase letters, digits and dashes. Required for JSON requests.

description string Required

What agents read to decide when to load it. Required for JSON requests.

body string Optional

The instructions as Markdown. Required for JSON requests.

bundle file Optional

Multipart only: a .zip up to 10 MB with SKILL.md at its root.

agents string[] Optional

Agent names that may load it. Omit or send an empty list for every agent.

visibility enum Optional

Who in the workspace can see and use it. To share outside the workspace, publish it.

Default workspace

One of private team workspace

# 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 bundle=@stripe-webhooks.zip
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"))
Response
{
  "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 conflict with code name_taken: update the existing skill instead.
  • 400 invalid_request with code bundle_invalid when the zip has no SKILL.md at its root or its front matter is missing name or description.

Retrieve a skill

GET https://api.duun.ai/v1/skills/{skill}

Returns one skill. You can pass its id or its name. Needs skills:read.

Path parameters

skill string 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

PATCH 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

skill string Required

The skill's id or name.

Body parameters

name string Optional

Renaming changes the #name agents and prompts use.

description string Optional

What agents read to decide when to load it.

body string Optional

The instructions as Markdown.

bundle file Optional

Multipart only: replaces body and every file.

agents string[] Optional

Replaces the list. Empty means every agent.

visibility enum Optional

Visibility inside the workspace.

One of private team 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"])
Response
{
  "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

DELETE 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

skill string 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")
Response
{ "id": "skl_pgmig41", "object": "skill", "deleted": true }

Publish a skill

POST 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

skill string Required

The skill's id or name.

Body parameters

visibility enum Required

link isn't listed; anyone with the link can view and install. public is listed on Explore for every Duun workspace.

One of private team workspace link public

version string Optional

Semantic version. Defaults to 1.0.0 for the first publish; after that it's required and must be higher than the last one.

release_notes string Optional

What changed. Required for every version after the first.

teams string[] Optional

Team names, when visibility is team.

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)
Response
{
  "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_error with code preflight_blocked when the skill references something you don’t own. The problems name each item.
  • 422 validation_error with code listing_incomplete for public: the skill needs a description and at least one example in its body.
  • 409 conflict with code version_exists when version isn’t higher than the last published version.

    Type to search the docs, help center and blog.