# Laravel AI SDK 1.2: Agent Skills That Load Only When Needed

By Dinesh Uprety
Published: 2026-10-26
Updated: 2026-10-26
Canonical: https://laranepal.com/blog/laravel-ai-sdk-12-agent-skills-that-load-only-when-needed

If you build an AI agent, its instructions tend to grow. First it is two lines, then it is your refund rules, your shipping rules, your tone of voice, and a pile of examples. Every request sends all of it to the model, whether the question needs it or not — and you pay for every token of it.

Laravel AI SDK 1.1, released on 5 October 2026, fixes exactly that with **Agent Skills**, and 1.2 (7 October) polishes the release further. Instead of one giant system prompt, you split instructions into small folders, and the model loads a folder only when the question calls for it. This guide walks through the setup, the code, and the gotchas worth knowing before you ship it.

## What a skill is

A skill is a folder with a `SKILL.md` file in it. The file has a short description at the top and the full instructions below. The agent always sees the list of names and descriptions — the catalog. It reads the full text only when it decides a skill is relevant. Think of a table of contents that the model can open chapter by chapter.

Skills follow an open standard, the same folder format coding agents use. That means a skill you write for your Laravel agent can be shared with the coding agent you use to build the app — and vice versa.

There are three tiers, and only the first one costs you tokens on every prompt:

1. **The catalog** — every skill's name and description, always visible to the model.
2. **The skill body** — the full `SKILL.md`, loaded only when the model asks for it.
3. **Bundled files** — reference documents inside the skill folder, loaded only when the model asks for one by path.

## Step 1: Install or upgrade

```bash
composer require laravel/ai:^1.2
```

The package asks for PHP 8.3 or newer and `illuminate/support` 12 or 13, and it needs `symfony/yaml` to read the skill files. If you are already on 1.0, this is a minor bump — but note that **default models changed** in 1.2. If cost or exact behaviour matters to you, pin your models explicitly instead of relying on defaults.

## Step 2: Create a skill

Put one folder per skill under `resources/skills`:

```
resources/skills/
└── refund-policy/
    ├── SKILL.md
    └── references/EDGE-CASES.md
```

The `SKILL.md` file starts with YAML frontmatter. The `description` is required — skills without one are ignored. The `name` is optional and defaults to the folder name:

```markdown
---
name: refund-policy
description: Use when a customer asks for a refund or disputes a charge.
---

# Refund Policy

Customers may request a full refund within 30 days of purchase.
Check the order date first. Orders older than 30 days are not eligible...

For annual plans, refund only the unused months — see references/EDGE-CASES.md.
```

Write the description as a trigger, starting with "Use when...". It is the only thing the model sees until it loads the skill, so a vague description means the skill never gets picked up.

![How Agent Skills load](https://laranepal.com/storage/XBsEp8MmBC8bxfyUs4sjFLoGw4xHd0DfXztWLJFF.png)

## Step 3: Give the agent its skills

Implement the `HasSkills` contract and return your skill sources from the `skills()` method. Sources can be directories, `Skill` objects, or closures that return skills — closures only run when the agent needs them:

```php
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasSkills;
use Laravel\Ai\Promptable;
use Laravel\Ai\Skills\Skill;

class SupportAgent implements Agent, HasSkills
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a friendly support agent for Acme.';
    }

    public function skills(): iterable
    {
        return [
            resource_path('skills'),
            base_path('.agents/skills'),
            new Skill(
                name: 'house-style',
                description: 'Use when you write copy for a customer.',
                instructions: 'Short sentences. No jargon. Sign off with "The Acme team".',
            ),
            fn () => $this->user->team->skills->map->toSkill(),
        ];
    }
}
```

That is all the wiring there is. The agent automatically gets one extra tool, `LoadSkill` — you never add it by hand. When a question comes in, the model sees the catalog ("house-style: Use when you write copy for a customer", "refund-policy: Use when a customer asks for a refund..."), calls `LoadSkill` with a skill name to read its instructions, and can call it again with a `path` to read a bundled file like `references/EDGE-CASES.md`.

One rule to remember: if two skills share a name, the source listed first wins.

## Step 4: Prompt it as usual

```php
$response = (new SupportAgent)->prompt('Can I get a refund for order 1042?');
```

Behind the scenes, the model loads the refund-policy skill, follows its instructions, and answers. A question about anything else never touches that skill — and never pays for its tokens.

## What else shipped in 1.1 and 1.2

Skills are the headline, but the two releases carry more that matters in production:

- **Tool approval.** Built-in tools — filesystem, MCP, sub-agent, similarity search — can now call `requireApproval()`. This is the human-in-the-loop guard for destructive actions: the agent asks before it deletes a file or runs a risky tool. It is **off by default**, so if you expose these tools to an autonomous agent, turn it on explicitly.
- **Cohere text generation.** Cohere joins as a text provider (its v2 Chat API, with streaming and structured output). It was previously available only for embeddings and reranking.
- **A `MoveFile` tool.** Moving a file used to take two tool calls (`CopyFile` + `DeleteFile`); now it takes one.
- **Failover that keeps going.** If a provider failover switches to a provider that does not support one of the agent's provider tools, the run no longer dies — it skips that tool and continues.
- **OpenAI classification with images (1.2.0).** OpenAI becomes a classification provider that can look at images, where previously only TypeSafe or OpenRouter offered classification, text-only.
- **No sampling params on Claude 4.7+ (1.2.0).** The SDK stops sending `temperature` and `top_p` to Claude 4.7 and newer, which previously caused a 400 error.
- **Failure events (1.2.2).** When an embeddings, image, audio, transcription, reranking or classification call fails, the SDK now fires an event (`EmbeddingsFailed`, `ClassificationFailed`, and friends) — even when failover quietly rescues the call. If your dashboard shows nothing while a job silently recovered, these events are the fix.
- **More classification coverage (1.2.3).** Classification reaches the `openai-compatible` driver, and image classification reaches TypeSafe and OpenRouter, plus a streaming fix for structured sub-agents.

## Gotchas before you ship

- **The description is the trigger.** "Use when a customer asks for a refund" gets picked up; "Refund stuff" does not. Write it like a rule, not a label.
- **Watch the 256 KB per-file limit.** A skill file bigger than that will not load as expected — keep reference material split across bundled files.
- **Approval is opt-in.** The SDK will not gate destructive tools for you. Decide per tool which ones need a human yes.
- **A loaded skill stays in the conversation.** With conversation memory enabled, a skill loaded on turn one is replayed on every later turn, so it keeps costing tokens for the rest of that conversation. Skills save the most on short, single-purpose chats.
- **The model needs tool calling.** Skills are delivered through a normal tool call, so the model and provider you use must support tool calling.
- **Pin your models.** Defaults changed in 1.2 — if you care about cost or stable behaviour, set models explicitly in `config/ai.php` instead of floating on defaults.

## The bottom line

Agent Skills turn a 400-line system prompt into a small catalog plus chapters the model opens on demand. Your short, always-relevant rules stay in `instructions()`; everything topic-specific — a policy, a procedure, a long style guide — moves into skills that only cost tokens when they are needed. One `composer update`, a folder of markdown files, and a `HasSkills` contract get you there.

**Sources:** [Laravel News — Laravel AI SDK 1.1 Adds Agent Skills and Cohere Chat](https://laravel-news.com/laravel-ai-sdk-1-1), [Laravel AI SDK 1.2: Skills, Tool Approval, Cohere](https://laravel-vuejs.space/laravel-ai-sdk-1-2-skills-approval-cohere)