Agent skills

⚠️

Preview — this feature is being built; the design below is the spec.

A skill is a reusable package of know-how: a short instructions file, plus any scripts, templates and reference files the task needs. You upload it once. In a request or an agent definition you list the skills available; the model sees only each skill’s name and one-line description, and loads the full contents only when the current task needs it. That keeps prompts small while giving the model deep, consistent procedures, such as “build our monthly finance pack” or “write a release note in our house style”.

Skills run inside code execution, so their scripts can actually run.

When to use them

A procedure your team repeats, with steps and checks the model should follow every time.
Brand or format rules with templates (reports, slides, spreadsheets).
Scripts that do the exact part of a job (calculations, file conversion) while the model does the judgement.

Package format

A skill is a ZIP with SKILL.md at the top level:

finance-pack/
  SKILL.md
  scripts/build_pack.py
  templates/pack.xlsx
  reference/chart-of-accounts.csv

SKILL.md starts with a short header:

---
name: finance-pack
description: Build the monthly finance pack from the ledger export. Use when asked for month-end reporting.
---
 
1. Load the ledger CSV from /mnt/input.
2. Run scripts/build_pack.py ...

Header field	Rules
`name`	1 to 64 characters, lower case, digits and `-`. Unique in the workspace.
`description`	Up to 1,024 characters. The model decides when to load the skill from this alone, so cover both its purpose and the situations that should trigger it.

Endpoints

Method	Path	Purpose
`POST`	`/v1/skills`	Create a skill from an uploaded ZIP (`file_id`, `purpose: "skill"`).
`GET`	`/v1/skills`	List skills (`limit`, `after_id`, `before_id`).
`GET`	`/v1/skills/{skill_id}`	Get a skill and its latest version.
`POST`	`/v1/skills/{skill_id}/versions`	Upload a new version.
`GET`	`/v1/skills/{skill_id}/versions`	List versions.
`DELETE`	`/v1/skills/{skill_id}`	Delete a skill and all versions.

Base URL https://app.syntic.ai/v1 (the paths above already include /v1), Authorization: Bearer sk_live_....

Create

Field	Type	Required	Details
`file_id`	string	Yes	The ZIP, uploaded with the Files API.
`display_title`	string	No	Shown in the Console.

The skill object

{
  "id": "skill_01JBXM4",
  "object": "skill",
  "name": "finance-pack",
  "description": "Build the monthly finance pack from the ledger export. Use when asked for month-end reporting.",
  "display_title": "Finance pack",
  "latest_version": "3",
  "created_at": 1791820800,
  "updated_at": 1792425600
}

Versions are numbered from 1 and immutable. Requests can pin a version or use latest.

Using skills in a request

Field	Details
`skills`	Array of `{ "id": "skill_...", "version": "3" or "latest" }`, up to 20. Requires the `syntic_code_execution` tool in `tools`.

Skills can also be attached to an agent definition so every session gets them.

Syntic also ships built-in skills with ids like syntic:xlsx, syntic:docx, syntic:pptx and syntic:pdf for working with office files.

Examples

# Upload the package and create the skill
curl https://app.syntic.ai/v1/files -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -F purpose=skill -F file=@finance-pack.zip
curl https://app.syntic.ai/v1/skills -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "Content-Type: application/json" -d '{"file_id":"file_01JBXM2","display_title":"Finance pack"}'
 
# Use it
curl https://app.syntic.ai/v1/chat/completions \
  -H "Authorization: Bearer $SYNTIC_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "model": "Amara S1.2",
    "stream": false,
    "tools": [{ "type": "syntic_code_execution", "files": ["file_01JBXL9"] }],
    "skills": [{ "id": "skill_01JBXM4", "version": "latest" }, { "id": "syntic:xlsx", "version": "latest" }],
    "messages": [{ "role": "user", "content": "Build the October finance pack from the ledger export." }]
  }'

const H = { Authorization: `Bearer ${process.env.SYNTIC_API_KEY}`, 'Content-Type': 'application/json' }
const skill = await (await fetch('https://app.syntic.ai/v1/skills', {
  method: 'POST', headers: H, body: JSON.stringify({ file_id: zipFileId }),
})).json()
 
const data = await (await fetch('https://app.syntic.ai/v1/chat/completions', {
  method: 'POST',
  headers: H,
  body: JSON.stringify({
    model: 'Amara S1.2',
    stream: false,
    tools: [{ type: 'syntic_code_execution', files: [ledgerFileId] }],
    skills: [{ id: skill.id, version: 'latest' }],
    messages: [{ role: 'user', content: 'Build the October finance pack.' }],
  }),
})).json()

import os, requests
 
base = "https://app.syntic.ai/v1"
h = {"Authorization": f"Bearer {os.environ['SYNTIC_API_KEY']}"}
 
versions = requests.get(f"{base}/skills/skill_01JBXM4/versions", headers=h).json()
print([v["version"] for v in versions["data"]])
 
with open("finance-pack.zip", "rb") as f:
    zip_id = requests.post(f"{base}/files", headers=h, data={"purpose": "skill"},
                           files={"file": ("finance-pack.zip", f)}).json()["id"]
new = requests.post(f"{base}/skills/skill_01JBXM4/versions", headers=h, json={"file_id": zip_id}).json()
print("new version", new["version"])

Errors

Unified envelope.

Status	`code`	Cause
400	`invalid_skill_package`	Not a ZIP, no `SKILL.md`, or a bad header. `message` says which.
400	`skills_require_code_execution`	`skills` sent without the code execution tool.
400	`too_many_skills`	More than 20 in a request.
404	`skill_not_found`	Unknown id or version, or another workspace’s skill.
409	`skill_name_taken`	A skill with this `name` already exists.
413	`skill_too_large`	Package over 30 MB unzipped.

Limits and pricing


Package size	30 MB unzipped, 500 files
Skills per workspace	500
Skills per request	20
Price	No skill fee. Loaded instructions are input tokens; scripts use code execution time.

Security

Skills can contain code that runs with whatever access the container has. Only install skills from people you trust, review scripts before uploading, and keep container network access off unless a skill needs it.

Build notes for the platform team

Reuse the existing skill loading logic; store packages via the Files API (purpose: "skill") per workspace.
At request time inject only name + description; mount the package at /skills/{name} in the container and let the model read SKILL.md on demand.
Depends on code execution and Files API.

Budgets & limits Write good skills

Was this page helpful?