Download the PHP package foodlz/laravel-ai-skills without Composer

Laravel AI Skills

Procedural knowledge skills for the Laravel AI SDK. Teach your AI agents how to behave — not just what to do.

Experimental RFC infrastructure. This package validates the Skills concept in real production use before it is proposed upstream to laravel/ai. The goal is to gather real-world feedback and edge cases that make the proposal persuasive to maintainers.

The Problem: Knowledge vs. Action

The Laravel AI SDK models agent capabilities as tools — PHP classes that perform an action: look up a record, send a message, call an API. This works perfectly for actions.

But many agents also need procedural knowledge — guidance on how to behave in a given situation:

• "Here is how to handle a refund request."
• "Here is the tone guide for customer support replies."
• "Here is the escalation policy when a user reports data loss."

Today you have two bad options:

A Skill is the missing first-class concept: a callable knowledge object with no input schema, whose sole purpose is to return guidance to the model when it decides that guidance is relevant.

Features

• Three delivery modes — OnDemand (one tool per skill), Full (injected into instructions), and Lite (meta-tool pair for high-skill-count agents)
• Prompt value object — load skill content from inline text or Markdown files (%{key} or {{ key }} substitution) or Blade views (native Blade syntax: {{ $key }})
• Runtime context injection — pass job-specific or conversation-specific data into skills via withContext()
• Database-driven skills — guide() is plain PHP; return an Eloquent query result for fully editable, admin-managed content
• Content caching — per-prompt or global config; disabled automatically in tests
• Full testing support — Skill::fake(), Skill::assertInvoked(), Skill::assertNotInvoked()
• php artisan make:skill — scaffolding that mirrors make:tool and make:agent
• #[WithSkills] attribute — declarative, IDE-navigable skill registration on agent classes
• #[AsSkill] attribute — name, description, mode, and cache in one place without override methods
• withSkillInstructions(static, dynamic) — prefix-cache-friendly Static → Skills → Dynamic prompt ordering
• Events — InvokingSkill and SkillInvoked for observability

Requirements

• PHP 8.3+
• Laravel 12+
• laravel/ai ^0.6

Installation

The service provider is auto-discovered. Publish the config file if you need to customise discovery paths or cache settings:

Quick Start

1. Scaffold a skill

This creates app/Ai/Skills/SigningSkill.php (and optionally resources/skills/signing.md):

2. Attach it to an agent

The simplest case — OnDemand skills only, no other action tools:

That's it. The Skillable trait provides a default tools() implementation that exposes all attached skills to the LLM automatically.

Both are required. implements HasTools is the SDK's gate — it only calls tools() when the agent declares that interface. use Skillable provides the actual implementation. One without the other means no skills are loaded.

Usage

Skill Modes

Set the mode on the #[AsSkill] attribute (or override mode() on the class):

Full Mode: withSkillInstructions()

Use withSkillInstructions() when any skill uses SkillMode::Full. It structures your system prompt in the order providers recommend for prefix cache performance: Static → Skills → Dynamic.

• staticPrompt — content that never changes across requests (base persona, global rules). Put this first for maximum cache reuse.
• Skills — Full-mode skill content goes here automatically.
• dynamicPrompt — per-request or per-user content (context, locale, user data). Goes last to keep the cached prefix as long as possible.

Both parameters are optional. Omit dynamicPrompt if you have no per-request content:

OnDemand and Lite skills are unaffected — they are exposed as tools and do not appear in instructions().

Mixing Action Tools with Skill Tools

When your agent has both action tools and skills, override tools() and use withSkillTools():

withSkillTools() merges your action tools with all skill tools and returns the combined array.

Dynamic Skills: HasSkills + skills()

For skills that need runtime data — the current user's plan, account type, locale, or any other request-time value — implement HasSkills and override skills():

The registry merges attribute skills and method skills automatically. Class strings and instances are both valid.

HasSkills is optional. Only implement it when you need to pass runtime context into skills via skills(). For static skill sets, #[WithSkills] on its own is sufficient.

The Prompt Value Object

Prompt implements Stringable and works anywhere a string is expected.

The %{key} and {{ key }} syntaxes both work for Prompt::text() and Prompt::file() — use whichever you prefer. Double-curly with a $ ({{ $key }}) is Blade syntax and applies only to Prompt::view().

Prompt is also usable in instructions() outside of skills:

Database-driven skill content

guide() is plain PHP — you are not limited to static files:

Skill Examples

Static skill — Markdown file, editable by non-developers

Dynamic skill — context injected at runtime

Caching

Per-prompt caching

Call .cache() on any Prompt instance to cache the resolved string output:

Global caching via config

Caching is disabled automatically in testing environments regardless of config.

Artisan Commands

Testing

Fake skill responses

Assert skills were (or were not) invoked

Unit test skill content directly

Skills are plain PHP objects — test guide() output without spinning up an agent:

Configuration

Publish the config file:

API Reference

Skillable trait

Skill abstract class

Events

Both events carry the Skill instance and the agent.

How It Works Internally

OnDemand and Lite skills are adapted to Laravel\Ai\Contracts\Tool at runtime via an internal SkillTool adapter — the LLM never knows the difference between a tool and a skill. Full-mode skills bypass the tool call entirely and have their content appended directly into the system prompt by withSkillInstructions().

The SkillRegistry reads #[WithSkills] via reflection and merges those with any skills returned by skills() if the agent implements HasSkills. Discovery is scanned from the paths configured in ai-skills.discovery.

Roadmap

• [x] php artisan skill:list — list all discovered skills with names, descriptions, and modes
• [x] php artisan skill:clear — clear skill content and discovery caches
• [x] Discovery caching
• [x] withSkillInstructions(static, dynamic)
• [ ] skill_read — LLM-accessible supplementary files per skill (via resourcePath()) — prefix-cache-friendly prompt ordering
• [ ] Prompt::url() — load skill content from a remote URL

Credits

• Inspired by anilcancakir/laravel-ai-sdk-skills — a community package that explored SKILL.md file-based skills and the meta-tool list_skills / skill pattern, which directly influenced the Lite mode and Prompt value object design in this package.
• Built on the Laravel AI SDK by Taylor Otwell and the Laravel team.

License

MIT — see LICENSE.