Back to Blog
Laravel AI SDK 1.1 Agent Skills: Load Instructions Only When Needed
Laravel AI SDK 1.1 adds Agent Skills so agents load SKILL.md instructions on demand via LoadSkill, plus Cohere chat, requireApproval on built-in tools, and failover that skips unsupported provider tools.
Back
Engineering
Table of contents
Laravel AI SDK 1.0 was about getting agents, tools, and conversation storage into a stable shape. Version 1.1.0 (released October 5, 2026) is the first minor since then, and the headline is Agent Skills.
If you have already been stuffing long policy text into instructions(), this release is the escape hatch. Skills keep that text out of the system prompt until the model decides it needs it.
Quick Answer
Upgrade with composer require laravel/ai:^1.1, then:
- Put task-specific instructions in
resources/skills/<name>/SKILL.md(YAML frontmatter needs adescription;namedefaults to the folder). - Implement
HasSkillsand return skill sources fromskills(). The agent gets oneLoadSkilltool. The model loads full instructions (and optional bundled files) only when a turn needs them. - Also useful in 1.1: Cohere text generation,
requireApproval()on built-in MCP/filesystem/similarity tools without subclassing, and failover that strips provider tools the next lab does not support instead of throwing. - If you rely on default models in
config/ai.php, review them after upgrade. 1.1 bumps several provider defaults.
Why skills matter more than another prompt trick
I have written support and ops agents where the system prompt grew every week. Refund rules. Escalation paths. Brand voice. Edge cases nobody wants in the main instructions forever.
That works until the prompt is expensive, noisy, and still missing the one policy you needed today.
Agent Skills follow the same folder format coding agents already use. Official docs describe a skill as a directory under resources/skills with a SKILL.md plus optional reference files:
text
resources/skills/
└── refund-policy/
├── SKILL.md
└── references/EDGE-CASES.mdFrontmatter looks like this:
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...Skills without a description are ignored. That is a silent footgun if you copy a markdown file and forget the YAML.
HasSkills and LoadSkill
Give an agent skills by implementing HasSkills and returning sources from skills():
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 support agent. Load a matching skill before you reply on policy questions.';
}
public function skills(): iterable
{
return [
resource_path('skills'),
base_path('.agents/skills'),
new Skill(
'house-style',
'Use when you write copy for a customer.',
view('skills.house-style')
),
fn () => $this->user->team->skills->map(
fn ($skill) => new Skill($skill->name, $skill->description, $skill->instructions)
),
];
}
}Sources can be directories, Skill objects, or closures. Closures run when the tool needs the list, so you can load per-team skills from the database without paying that cost on every cold construction.
The agent receives a single LoadSkill tool. Names and descriptions stay in the tool schema. Full SKILL.md bodies load only when the model calls the tool. Calling again with a path reads a bundled text file inside that skill folder. Binary files and files larger than 256 KB are rejected.
You can also add new LoadSkill([...]) in tools() directly. If you declare both HasSkills and a manual LoadSkill, the SDK merges into one tool and logs a warning, because providers reject duplicate tool names. Pick one path.
Pointing at base_path('.agents/skills') is the practical win for teams already writing skills for coding agents. Share the folders that make sense for both. Do not dump every "use Pest" coding skill into a customer support agent just because the directory is convenient.
Surrounding 1.1 changes worth the upgrade note
Skills are the reason I would write this post. A few other 1.1 items matter in production:
Cohere text generation. Cohere was already available for embeddings and reranking. 1.1 adds text via Cohere's v2 Chat API (streaming, tools, structured output, reasoning). Default model is command-a-03-2025. Document attachments and citations are not supported yet. You can still pass Cohere-specific options through provider options.
Approval on built-in tools. MCP, agent, similarity search, and filesystem tools implement Approvable, so you can call requireApproval() without subclassing. Approval stays off by default. Use it when a built-in tool can mutate something you care about.
Failover skips unsupported provider tools. Before 1.1, an agent with WebFetch on ['anthropic', 'openai'] could die mid-failover when OpenAI rejected WebFetch. The text loop now strips provider tools the current provider cannot run, then continues. On a provider without hosted tool search, ToolSearch unwraps into regular tools. Multiple ToolSearch wrappers still throw.
Default model bumps. Anthropic and Gemini defaults moved in this release. If you never set models explicitly, your next deploy may talk to different models. That is a behavior change even when your code did not change.
Also in the same release notes: MoveFile for filesystem tools, Azure tool search, Groq web search and code execution on GPT-OSS models, OpenRouter web search location, and self-hosted Laya classification through the existing TypeSafe driver.
What about 1.2.0?
v1.2.0 shipped two days later (October 7, 2026). It is a small follow-up: structured output edge cases, OpenAI Decisions classification with image attachments, Anthropic default/model sampling tweaks for Claude 4.7+. If you are jumping from 1.0, go straight to ^1.2 and still treat skills as the 1.1 story.
As of 20 November 2026, laravel/ai v1.4.1 is the current release on GitHub and Packagist. v1.4.0 added agent recovery from tool failures (laravel/ai PR #1191), which is worth knowing if your agents call flaky external tools in production.
My take
Agent Skills are the first Laravel AI feature that feels like it was designed for long-lived product agents, not demos. Progressive disclosure is not marketing fluff here. You pay for a short catalog on every turn, and you pay for the full policy only when the model asks.
My opinion: start with one or two high-value skills (refund policy, escalation, brand voice), keep instructions() short, and raise MaxSteps enough that LoadSkill plus the real tools can finish. Do not turn every README into a skill on day one.
If you already shipped agents on 1.0, this is a low-drama upgrade compared with the 0.11 to 1.0 conversation schema migration. Read the release notes, bump the constraint, review default models, then add skills where your system prompt is already too long.
Sources
- laravel/ai v1.1.0 release
- laravel/ai v1.2.0 release
- laravel/ai v1.4.0 release
- laravel/ai v1.4.1 release
- laravel/ai PR #1191 (agents recover from tool failures)
- Laravel AI SDK docs: Skills
- laravel/ai PR #1054 (Agent Skills support)
- laravel/ai PR #1102 (HasSkills / LoadSkill)
- laravel/ai PR #1078 (Cohere text generation)
- laravel/ai PR #1097 (approval for built-in tools)
- laravel/ai PR #1080 (skip unsupported provider tools on failover)
- Laravel News: Laravel AI SDK 1.1 Adds Agent Skills and Cohere Chat
Comments
No comments yet
Loading comments...