> ## Documentation Index
> Fetch the complete documentation index at: https://trytilde.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Give agents reusable instructions and files as Agent Skills, from your own code, from Git, from the Tilde catalog, or written in the Tilde editor.

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](https://agentskills.io) 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.

```markdown SKILL.md theme={"system"}
---
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.

<CodeGroup>
  ```typescript TypeScript theme={"system"}
  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.",
  });
  ```

  ```python Python theme={"system"}
  import tilde

  # Relative to this file.
  SKILLS = tilde.define_skills("skills")
  ```
</CodeGroup>

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](/docs/frameworks/overview).

## 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.

```typescript Read skills directly theme={"system"}
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](/docs/skills/management#agent-capabilities-for-skills), 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](/docs/deployment/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.

## Next steps

<Columns cols={2}>
  <Card title="Manage skills" href="/docs/skills/management">
    Add sources, edit skills, and give them to agents.
  </Card>

  <Card title="Framework integrations" href="/docs/frameworks/overview">
    See how each framework loads skills.
  </Card>
</Columns>