AgentSkyDocs
OverviewQuickstartCLI referenceAPI referenceAPI GatewayCapabilitiesagent.tomlChannels

Skills

Reusable instruction + script bundles your agents load on demand. Upload a skill once to your universe, attach it to any agent by reference — pinned to an immutable revision or tracking latest — or point an agent at a GitHub repo's .claude/skills/ directory. The endpoint-level reference lives in the API reference.

What a skill is

A skill is a directory with a SKILL.md at its root plus any supporting files — reference docs, templates, and executable scripts the agent runs with bash. SKILL.md starts with YAML frontmatter:

markdown
---
name: pdf-processing
description: Extract text and tables from PDF files. Use when working with PDFs.
---

# PDF processing

Run \`scripts/extract.py <file>\` with bash and summarize its output.

Frontmatter rules (enforced at upload): name ≤64 chars, lowercase letters, digits, and hyphens only; description non-empty, ≤1024 chars — it is what the agent matches your request against, so say what the skill does and when to use it. Bundles are capped at 30 MB uncompressed; binary files are fine.

Upload

POST /v1/skills takes multipart files entries — one zip archive, or individual files whose multipart filenames carry their relative paths. Zip entries keep their unix exec bit, so bundled scripts arrive runnable (loose files default to non-executable — ship executables via zip).

bash
curl -X POST https://api.agentsky.dev/v1/skills \
  -H "Authorization: Bearer ast_..." \
  -F "files=@pdf-processing.zip"
# -> { "skill": { "id": "skill_…", "latestRevisionId": "skr_…", … }, "revision": { … } }

Skills are scoped to your universe: any token with access can list, attach, and delete them.

Revisions

Every upload is an immutable revision; the skill keeps a latest pointer. A new revision (POST /v1/skills/{skillId}/revisions) is a complete snapshot — omitted files are not carried over — and its SKILL.md name must match the skill's name. Deleting is reference-aware: a skill attached to an agent returns 409 skill_in_use; a pinned revision returns 409 revision_in_use; detach first.

Attach to an agent

The skills array on agent create/PATCH (max 20 entries; PATCH replaces the whole array, omitted preserves):

json
"skills": [
  { "type": "skill",  "skillId": "skill_…", "version": "latest" },
  { "type": "skill",  "skillId": "skill_…", "version": "skr_…" },
  { "type": "github", "url": "https://github.com/org/repo", "ref": "main" }
]

latest resolves to a concrete revision when a session's pod is provisioned — a running session never changes skills because you uploaded a new revision; new sessions pick up the new latest. Pin a skr_… id for exact reproducibility. Changes to the array take effect at the next session start.

In agent.toml the same entries are [[skills]] tables, and sky deploy re-applies them.

The GitHub shortcut

A { "type": "github" } entry skips the store entirely: at every session start the repo is shallow-cloned and its root .claude/skills/<name>/SKILL.md directories — exactly one level deep — are installed. ref pins a branch or commit SHA (default branch when omitted); a branch re-resolves at each session start. For private repos, set tokenSecretRef to the name of an agent secret holding a clone token.

Not discovered: a bare .claude/skills/SKILL.md, anything nested deeper than one level, a skills/ directory outside .claude, or a .claude/skills inside a subdirectory. A repo you attach is part of your agent's trust boundary — anyone who can commit to it ships instructions your agent will follow.

How agents use skills

At session start each skill lands on the pod's filesystem where the engine reads it. The agent sees every skill's name and description, reads SKILL.md when a task matches, and runs bundled scripts with bash — script output enters the conversation, script code does not. Agents can also install more skills mid-session from the marketplace (actl skill).