# Agent Skills

> Source: https://trigger.dev/docs/ai-chat/patterns/skills

The AI Agents and Prompts surface ships as part of the **v4.5 release candidate**. Install with `@trigger.dev/sdk@rc` (or pin `4.5.0-rc.0` or later) to use these features — they aren’t yet on the latest stable, and APIs may still change before the 4.5.0 GA. See [supported AI SDK versions](https://trigger.dev/docs/ai-chat/reference#compatibility)
 and the [AI chat changelog](https://trigger.dev/docs/ai-chat/changelog)
 for details.

Agent skills are reusable capabilities you ship as folders — a `SKILL.md` describing when and how to use them, plus optional scripts, references, and assets. The chat agent sees a short description of each skill in its system prompt, loads the full instructions on demand via a `loadSkill` tool, and invokes the bundled scripts via `bash` — all without you wiring anything up manually. Built on the [AI SDK cookbook pattern](https://ai-sdk.dev/cookbook/guides/agent-skills)
. Works with any provider (OpenAI, Anthropic, Gemini, etc.) — not tied to Anthropic’s server-side skills.

[​](https://trigger.dev/docs/ai-chat/patterns/skills#why-skills)

Why skills?
-------------------------------------------------------------------------------

Compared to regular AI SDK tools:

*   **Tools** are typed functions you pre-declare. Great when you know up-front exactly what capability the agent needs.
*   **Skills** are folders the model discovers and reads on demand. Great when the capability is a bundle of instructions + helper scripts that would be awkward to encode as a single tool.

PDFs are the canonical example: you don’t want to ask the LLM to parse PDF bytes inline. You want it to `bash scripts/extract.py report.pdf` using a bundled `pdfplumber` wrapper. A skill ships the script, the instructions, and any reference notes together. Dashboard-editable `SKILL.md` is on the roadmap so a platform team can tighten a skill’s description or “when to use” text without a redeploy. Today, skills are SDK-only — defined in your task code and shipped with each deploy.

[​](https://trigger.dev/docs/ai-chat/patterns/skills#trust-model)

Trust model
--------------------------------------------------------------------------------

Skills are **developer-authored code**, not end-user-supplied. The same developer who writes the `chat.agent()` writes the skill bundle. The trust boundary is identical to any `tool.execute` handler the developer writes — scripts run directly in the Trigger.dev worker container, no sandboxing required. This makes skills different from the Claude Code / end-user model where arbitrary user-provided skills need isolation. Don’t accept skill paths from untrusted input.

[​](https://trigger.dev/docs/ai-chat/patterns/skills#skill-folder-layout)

Skill folder layout
------------------------------------------------------------------------------------------------

A skill is a directory under your project (conventionally `trigger/skills/{id}/`):

    trigger/skills/time-utils/
    ├── SKILL.md              # Required — frontmatter + instructions
    ├── scripts/
    │   ├── now.sh
    │   └── add.sh
    ├── references/
    │   └── timezones.txt
    └── assets/               # Optional — templates, data files, etc.
    

### 

[​](https://trigger.dev/docs/ai-chat/patterns/skills#skill-md)

SKILL.md

Frontmatter is YAML-subset — only `name` and `description` are required:

    ---
    name: time-utils
    description: Compute and format dates/times in arbitrary timezones. Use when the user asks "what time is it", timezone conversions, or date math.
    ---
    
    # Time utilities
    
    ## When to use
    
    - The user asks for the current time in a timezone
    - The user wants date math ("3 days from now")
    
    ## Scripts
    
    ### `scripts/now.sh [TZ]`
    Prints the current time in the given IANA timezone (default `UTC`).
    
    ### `scripts/add.sh DAYS [TZ]`
    Prints a date `DAYS` days from now.
    
    ## Tips
    - IANA timezone names only (`America/New_York`, not `EST`).
    - See `references/timezones.txt` for a cheat-sheet.
    

The **description** is what the model sees in its system prompt — write it like you’re explaining to the agent when to reach for the skill. The **body** is loaded on demand via the `loadSkill` tool when the agent decides to use the skill. Write it like documentation for the agent.

[​](https://trigger.dev/docs/ai-chat/patterns/skills#defining-and-using-a-skill)

Defining and using a skill
--------------------------------------------------------------------------------------------------------------

trigger/chat.ts

    import { chat } from "@trigger.dev/sdk/ai";
    import { skills } from "@trigger.dev/sdk";
    import { streamText, stepCountIs } from "ai";
    import { anthropic } from "@ai-sdk/anthropic";
    
    const timeUtilsSkill = skills.define({
      id: "time-utils",
      path: "./skills/time-utils",
    });
    
    export const agent = chat.agent({
      id: "docs-chat",
      onChatStart: async () => {
        chat.skills.set([await timeUtilsSkill.local()]);
      },
      run: async ({ messages, signal }) => {
        return streamText({
          model: anthropic("claude-sonnet-4-5"),
          messages,
          abortSignal: signal,
          ...chat.toStreamTextOptions(),
          stopWhen: stepCountIs(15),
        });
      },
    });
    

`skills.define({ id, path })` does two things:

1.  Registers the skill with the Trigger.dev build system so the CLI **automatically bundles the folder** into your deploy image at `/app/.trigger/skills/{id}/`. No `trigger.config.ts` changes, no build extension — it just works.
2.  Returns a `SkillHandle` you use at runtime.

`skill.local()` reads the bundled `SKILL.md` from disk and returns a `ResolvedSkill` with the parsed frontmatter + body + on-disk path. `chat.skills.set([...])` stores the resolved skills for the current run. `chat.toStreamTextOptions()` spreads them into `streamText` automatically:

*   The frontmatter `description` lands in the system prompt under “Available skills:”.
*   Three tools are added: `loadSkill`, `readFile`, `bash` — scoped per skill.

[​](https://trigger.dev/docs/ai-chat/patterns/skills#what-gets-auto-injected)

What gets auto-injected
--------------------------------------------------------------------------------------------------------

When you spread `chat.toStreamTextOptions()` with skills set, the AI SDK call receives three tools:

### 

[​](https://trigger.dev/docs/ai-chat/patterns/skills#loadskill--name-)

`loadSkill({ name })`

Returns the full `SKILL.md` body for the named skill. The model calls this first when it decides a skill is relevant, to load the full instructions.

### 

[​](https://trigger.dev/docs/ai-chat/patterns/skills#readfile--skill-path-)

`readFile({ skill, path })`

Reads a file inside the skill’s bundled folder. Paths are relative to the skill’s root and are rejected if they attempt to escape via `..` or absolute paths. Output is capped at 1 MB per call. Use for reference files and templates that the model should read literally:

    readFile({ skill: "time-utils", path: "references/timezones.txt" })
    

### 

[​](https://trigger.dev/docs/ai-chat/patterns/skills#bash--skill-command-)

`bash({ skill, command })`

Runs a bash command with `cwd` set to the skill’s root. Stdout and stderr are captured and returned (each capped at 64 KB per call, with tail truncation). The turn’s abort signal propagates — cancelling the run kills the child process. Use to invoke the skill’s bundled scripts:

    bash({ skill: "time-utils", command: "bash scripts/now.sh America/Los_Angeles" })
    

Script runtime expectations are yours to manage. If your skill uses `extract.py`, your deploy image needs Python — add it via your build config the same way you would for any other task dependency.

[​](https://trigger.dev/docs/ai-chat/patterns/skills#how-discovery-works-in-the-model)

How discovery works in the model
--------------------------------------------------------------------------------------------------------------------------

The model sees a short preamble appended to your system prompt:

    Available skills (call `loadSkill` to read the full instructions before using one):
    - time-utils: Compute and format dates/times in arbitrary timezones...
    - pdf-processing: Extract text from PDFs, fill forms...
    

When the user asks something that matches a description, the model calls `loadSkill({ name: "time-utils" })` to load the body, then follows the body’s instructions — typically by calling `bash` or `readFile` on the bundled scripts. This is **progressive disclosure**: each skill costs ~100 tokens up front (its one-line description), and only the ones the model actually uses pay the full context cost.

[​](https://trigger.dev/docs/ai-chat/patterns/skills#mixing-skills-with-custom-tools)

Mixing skills with custom tools
------------------------------------------------------------------------------------------------------------------------

If you also define your own AI SDK tools, pass them through `chat.toStreamTextOptions()` so the merge is explicit:

    return streamText({
      model: anthropic("claude-sonnet-4-5"),
      messages,
      abortSignal: signal,
      ...chat.toStreamTextOptions({
        tools: {
          webFetch,       // your tool
          deepResearch,   // your tool
        },
      }),
      stopWhen: stepCountIs(15),
    });
    

Your tools win on name conflicts. (Pick names that don’t collide with `loadSkill` / `readFile` / `bash` to keep things predictable.) Also declare those same tools on the agent’s [`tools`](https://trigger.dev/docs/ai-chat/tools)
 config. `toStreamTextOptions` merges them with the skill tools for the model call, while the config option threads them into history re-conversion so any `toModelOutput` survives across turns. The auto-injected skill tools (`loadSkill` / `readFile` / `bash`) don’t define `toModelOutput`, so they don’t need to be on the config.

[​](https://trigger.dev/docs/ai-chat/patterns/skills#bundling)

Bundling
--------------------------------------------------------------------------

Bundling is **built-in to the CLI** — there’s no extension to import. When you run `trigger deploy` or `trigger dev`:

1.  esbuild bundles your task code as usual.
2.  The CLI forks the indexer locally against the bundled output, collects every `skills.define({ path })` registration.
3.  Each skill’s folder is copied to `{outputPath}/.trigger/skills/{id}/` via a recursive copy.
4.  The existing Dockerfile `COPY` picks up `.trigger/skills/` along with the rest of the bundle — no Dockerfile changes.

If you’re running `trigger dev`, the same layout appears in the local dev output directory, so `skill.local()` works the same way.

[​](https://trigger.dev/docs/ai-chat/patterns/skills#path-scoping-rules)

Path scoping rules
----------------------------------------------------------------------------------------------

*   `skill.path` always resolves to `${process.cwd()}/.trigger/skills/{id}/` at runtime. Don’t hardcode paths elsewhere.
*   `readFile` rejects `..` segments and absolute paths — the tool only exposes files inside the skill’s own directory.
*   `bash` runs with `cwd` set to the skill’s root. Inside the script, relative paths resolve against the skill directory.
*   Cross-skill access isn’t provided — each skill is isolated by design. If two skills need to share data, either duplicate the shared file or consolidate the skills.

[​](https://trigger.dev/docs/ai-chat/patterns/skills#current-limitations)

Current limitations
------------------------------------------------------------------------------------------------

*   `skill.resolve()` (backend-managed overrides) is not available yet — use `.local()` for now. Dashboard-editable `SKILL.md` is on the roadmap.
*   No per-skill metrics in the dashboard yet.
*   No Anthropic `/v1/skills` integration — use the portable path today; we’re tracking the Anthropic optimization separately.

[​](https://trigger.dev/docs/ai-chat/patterns/skills#full-example)

Full example
----------------------------------------------------------------------------------

See [`projects/ai-chat/src/trigger/skills/time-utils/`](https://github.com/triggerdotdev/references/tree/main/projects/ai-chat/src/trigger/skills/time-utils)
 in the [references repo](https://github.com/triggerdotdev/references)
 for a working skill that bundles two bash scripts and a reference cheat-sheet, wired into a `chat.agent` that answers timezone questions.

[​](https://trigger.dev/docs/ai-chat/patterns/skills#related)

Related
------------------------------------------------------------------------

*   [AI SDK cookbook — Agent Skills](https://ai-sdk.dev/cookbook/guides/agent-skills)
     — the userland pattern we build on
*   [Anthropic Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
     — Anthropic’s codified version (server-side, optional future integration)

Was this page helpful?

YesNo

[Previous](https://trigger.dev/docs/ai-chat/patterns/large-payloads)
[OOM resilienceRecover from out-of-memory errors mid-turn by automatically retrying the failed turn on a larger machine — without losing the in-flight user message or re-processing completed turns.\
\
Next](https://trigger.dev/docs/ai-chat/patterns/oom-resilience)

Ctrl+I

Assistant

Responses are generated using AI and may contain mistakes.