Give your server skills

A skill tells an agent how to do a whole job with your tools: what to call, in what order, and when to stop and ask. Each one is a folder in skills/, and it goes live with the deploy it's in, so a preview shows it first and a restore brings the old one back.

Write a skill

On a server's Skills tab, choose New skill. Or start one in your repository:

sokie skills new publish-a-take

That writes skills/publish-a-take/SKILL.md:

---
name: publish-a-take
description: Render the edit and hand back the link. Use when someone asks to publish a take.
---

## Workflow

1. Call `getEdit` and check it has a render.
2. Call `publishRecording`, and ask first.

## Limits

- Never publish a take nobody asked you to.

The name is the folder's name: lowercase words joined by hyphens, up to 64 characters. It's the open Agent Skills format, so there's nothing Sokie-only to learn.

The description is what agents choose by. It's all they see until they pick the skill, so say what it does, then when to use it, in up to 1,024 characters.

Keep the file under 500 lines. Put longer detail in references/ or assets/ beside SKILL.md, and say in the instructions when to read it.

Check it

sokie check and every deploy check each skill. Most findings are warnings, and a few stop the deploy, such as a key in the text or a folder with no SKILL.md. sokie skills lists them, with the tools each skill names:

sokie skills

sokie skills show publish-a-take

To see what a deployed server has live, with what asks first, add --server <slug>.

A deploy that removes a tool a skill still names says so on the pull request, before it merges.

A skill gives no permission. It can tell an agent to call a tool, but What agents may do still decides every call. A tool that's off stays off, and Ask first still asks.

Edit a skill

On a skill's page, choose Edit. Saving works the way a tool's description does: on a server with a repository it opens a pull request, and with no repository it deploys. If production moved on while you were editing, nothing is saved and your changes stay on the page.

Renaming a skill is a change in your repository, because its name is its folder's.

Try it with your agent

Checks can't say whether an agent follows a skill. A try can, because the server sees what really happened.

1. On the skill's page, choose Try with my agent, and write what you'd ask.
2. Add the preview to your agent, sign in, and ask in a new conversation. Don't name the skill.
3. Choose Start watching. Your own calls appear as they arrive, with whether your agent read the skill and what was refused.

Or from a terminal:

sokie skills try publish-a-take --preview 52 --ask "Publish the take called Onboarding demo"

With no previews, a try on your team's own server runs on production, on real data. Use a Read only connection to look without changing anything.

People connect to a server open to its API's users, or to anyone, with their own accounts or none, so your calls can't be told from theirs on production. A try needs a preview there.

Save as a case, or --save, writes tests/skills/<name>.json, so you can ask the same thing again after a change. These cases use your own agent, so they run when you ask, never on a preview.

How skills reach agents

An agent that connects to your server can read its skills right away. Clients that read skills see them as the server's, and every other agent gets one extra tool, readSkill, that fetches them. If you'd rather not add the tool, switch off Offer skills to every agent on the Skills tab. Reading a skill doesn't count as a tool call.

Adding skills to an agent makes it reach for them more reliably. The Skills tab has these steps, and on a listed server its page has them for your users.

Sokie can't count when an installed copy is used.

Who can read them

Who can read a server's skills follows who can connect.

On a server open to its users, a skill's text is public by default, so anything in it is too. Turning Readable before signing in off keeps it to signed-in callers, and install commands stop working. Turning it on is for an admin, and a member can ask for it.

To install a team's skills:

sokie skills add my-server

They go in .claude/skills. --to cursor, --to codex or a folder puts them elsewhere.

Hand them to a directory

Some directories and clients want a Git repository or a folder. This writes the skills with each client's manifest, and your server's address, with no secrets:

sokie skills package

Commit it or hand it over. Sokie submits nothing for you.

Limits