Skills

Skills extend what the agent can do. Each one is a SKILL.md describing a capability plus any helper scripts the skill invokes (Python, shell, JS, etc.). Skills are tenant-scoped: install once, every session in your tenant sees them. Bundle the skill as a zip and POST it.

POST /v1/skills/{name}

Body is the raw zip bytes. The bundle must contain a SKILL.md at its root. A single wrapper directory is auto-stripped, so both shapes work:

# Flat
SKILL.md
run.py

# Wrapped (zip -r myskill.zip myskill/)
myskill/
├── SKILL.md
└── run.py

zip -r myskill.zip myskill/
curl -X POST "$POKEE_API/v1/skills/myskill" \
  -H "Authorization: Bearer $POKEE_KEY" \
  -H "Content-Type: application/zip" \
  --data-binary @myskill.zip

Response (201):

{
  "name": "myskill",
  "files": ["SKILL.md", "run.py"],
  "total_bytes": 158,
  "skill_md_size": 130
}

Naming: [a-z0-9_-], 1–64 chars, must start with [a-z0-9]. The custom- prefix is reserved.

Limits: 1000 entries, 50 MB total uncompressed, 25 MB per file. Symlinks, devices, and absolute paths are rejected; path-traversal attempts (../escape.txt) return 400 with nothing written to disk.

Effective when: sessions created after the upload see the new skill. Sessions already running keep using whatever skills they discovered at start. Re-uploading the same name swaps in the new bundle and drops files that aren't in it (replace, not merge).

Atomicity: the bundle is unpacked in a staging directory, validated end-to-end, then atomically swapped into place. A bad bundle leaves the previous version untouched.

GET /v1/skills

List custom skills installed in the workspace:

curl "$POKEE_API/v1/skills" -H "Authorization: Bearer $POKEE_KEY"

[
  {"name": "myskill", "skill_md_size": 130, "modified": 1777523329.22}
]

Built-in skills (the ones Pokee provisions for your tenant at deal time) are not listed here — this is workspace-uploaded skills only.

DELETE /v1/skills/{name}

Uninstall a custom skill. Returns 204 or 404.

curl -X DELETE "$POKEE_API/v1/skills/myskill" \
  -H "Authorization: Bearer $POKEE_KEY"

Errors