Skills

A skill is a published, versioned bundle of instructions — plus any scripts, templates, or reference files it needs — that an agent can pull in at run time. Think of it as a package registry for agent capabilities: publish a skill once per application, then reference it by name from any manifest, pinned to a version or always-latest.

Authoring a skill

A skill is a directory with a SKILL.md at its root:

support-triage-playbook/
  SKILL.md
  templates/
    reply.md
  scripts/
    classify.py

SKILL.md opens with frontmatter the control plane reads to name and version the skill — everything after it is the instructions the agent reads via read_skill:

---
name: support-triage-playbook
version: "1.0"
description: How to triage an incoming support ticket and draft a reply.
---

1. Classify the ticket with `scripts/classify.py`.
2. Load `templates/reply.md` and fill it in based on the classification.
3. If the customer is on an enterprise plan, ask a human before sending.

• name — lowercase letters, digits, and dashes (max 64 chars).
• version — any string, just not containing @. A published version's content is immutable — publishing the same files again under the same version is a no-op, publishing different files under an existing version is rejected. Bump the version instead.
• description — shown to the model when deciding whether to use the skill, so make it count.

Publishing

sypho skill push [path]   # defaults to the current directory
sypho skill list          # latest version of every skill

The control plane builds the bundle and computes its digest — the same files always hash the same, however they were uploaded (CLI or dashboard).

Using a skill from a manifest

Reference it from an entrypoint, and declare the three gateway tools it needs:

{
  "entrypoints": {
    "main": {
      "tools": ["read_skill", "read_skill_file", "run_skill_script"],
      "skills": ["support-triage-playbook"]
    }
  }
}

• "support-triage-playbook" — the latest non-deprecated version at run creation.
• "support-triage-playbook@1.0" — pinned to an exact version, deprecated or not. A run keeps whatever it was pinned to for its whole life, including on replay.

See Entrypoints for how skills sits alongside tools/allowed_sub_agents.

Calling it at runtime

Skill tools run inside the gateway sandbox itself, not as MCP calls — the agent container never holds the skill's files.

Tool	Purpose
read_skill	Load a skill's instructions (SKILL.md, minus frontmatter) and the list of its other files
read_skill_file	Read one bundled file by path — a template, reference doc, or script source
run_skill_script	Run a bundled script (.py/.sh/.js/.mjs) sandboxed, with arguments

{"tool": "read_skill", "args": {"skill_name": "support-triage-playbook"}}

{"tool": "run_skill_script", "args": {
  "skill_name": "support-triage-playbook",
  "script": "scripts/classify.py",
  "args": ["--ticket-id", "482"]
}}

run_skill_script returns exit_code, stdout, stderr, and output_files — files the script wrote, copied into the run's workspace so your own code (or a later tool call) can read them with workspace_read.

Deprecating and removing

PATCH /skills/support-triage-playbook/1.0  { "deprecated": true }

A deprecated version stops resolving for unpinned ("name") references, but a run explicitly pinned to it ("name@1.0") is unaffected. Deleting a skill or version is blocked while any unfinished run still has it pinned — finish or cancel those runs first.