Skills

A skill is a folder of instructions and files that teaches an agent how to do one job, such as handling refunds or writing a release note. Each skill has a SKILL.md file, and any scripts, templates, or reference files it uses. Tilde uses the Agent Skills format. An agent sees each skill’s name and description up front, and reads the rest only when it needs it. You can give an agent many skills without filling its context.

SKILL.md

---
name: refunds
description: Issue a refund for a customer order. Use when a customer asks for their money back.
---

1. Find the payment for the order.
2. Check the refund policy in `policy.md`.
3. ...

Where skills come from

Tilde groups skills into sources. The UI calls them groups.

Source	What it holds	Who edits it
Bundled	Skills in the agent’s own code. `tilde deploy` registers them with each deployment.	Your code. They are read-only in Tilde.
Catalog	Built-in Tilde skills, and curated skills from trusted providers such as Anthropic, Microsoft, Cloudflare, AWS, Stripe, and Vercel.	Tilde syncs them. They are read-only.
Git	Every `SKILL.md` in a GitHub repository, at a branch and optional path.	Your repository. They are read-only in Tilde.
Editor	Skills written in the Tilde skill editor, or by an agent.	Operators and permitted agents.

Bundled skills belong to one agent, and are pinned to each deployment. A new deployment ships its own copy. All other sources are live: when a source changes, every agent that uses it receives the new version on its next invocation, with no redeploy. A bundled skill replaces an assigned skill with the same name.

Bundle skills in your code

Put each skill in its own folder, with a SKILL.md. Then declare the folder, so tilde deploy ships it.

import { defineSkill, defineSkills } from "@trytilde/sdk";

// Every folder under ../skills that holds a SKILL.md.
export const skills = defineSkills({
  dir: new URL("../skills", import.meta.url),
});

// Or one skill written in code.
export const tone = defineSkill({
  name: "reply-tone",
  description: "How to word replies to customers.",
  instructions: "Be direct and warm. Keep replies under 80 words.",
});

import tilde

# Relative to this file.
SKILLS = tilde.define_skills("skills")

Frameworks with their own skills, such as Mastra, Agno, CrewAI, and OpenAI Agents with a shell tool, declare skills in the framework’s own way. Their adapters register those skills for you. See Framework integrations.

How agents receive skills

Every invocation tells the agent which skills it has, and at which version. The SDK keeps the skills on local disk, in one folder for each agent. On each invocation it downloads only new or changed skills, and deletes removed ones. A skill is swapped in whole, so the agent never reads half of one. The SDK then gives the skills to your framework in one of two ways:

Natively, for frameworks that load skills from a directory. ctx.skills.directory() returns the folder.
As tools, for frameworks with no skills concept. The agent receives list_skills and read_skill tools, and a summary of its skills in its instructions.

Read skills directly

const root = await ctx.skills.directory();   // skills on disk
const all = await ctx.skills.list();          // names, descriptions, and files
const body = await ctx.skills.read("refunds"); // SKILL.md text

Skills an agent manages itself

With the right capabilities, an agent can manage skills at runtime through ctx.skills:

assign and unassign give skills to itself or other agents.
write saves a skill into an editor source, as its next version.
sync pulls the latest version of a Git or catalog source.

These methods are available in the TypeScript SDK.

Storage and limits

Tilde stores small text files in PostgreSQL. It stores every other file, content addressed, in the skills bucket. See Deploy the gateway.

Limit	Value
Skill name	Lowercase letters, digits, `-`, and `_`. Unique within a source.
`SKILL.md`	1 MiB.
Any other file	10 MiB.
Whole skill	64 MiB, and 2,048 files.
Paths	Relative paths only. No symlinks.

Each distinct set of files is an immutable version. Its hash covers each file’s path, content, and executable bit.

Get started

Platform

Framework integrations

Security

Observability

Deployment

Where skills come from

Bundle skills in your code

How agents receive skills

Skills an agent manages itself

Storage and limits

Next steps

Manage skills

Framework integrations

​Where skills come from

​Bundle skills in your code

​How agents receive skills

​Skills an agent manages itself

​Storage and limits

​Next steps

Manage skills

Framework integrations

Where skills come from

Bundle skills in your code

How agents receive skills

Skills an agent manages itself

Storage and limits

Next steps