truthanb/laravel-ai-skills

Agent Skills (agentskills.io) support for Laravel AI

v0.1.0 2026-02-07 17:05 UTC

Requires

• php: ^8.2
• laravel/ai: ^0.1
• symfony/yaml: ^7.0

Requires (Dev)

• orchestra/testbench: ^10.0
• phpunit/phpunit: ^12.0

MIT

• Benjamin Truthan

• laravel
• Agent
• ai
• skills
• agentskills

README

Agent Skills (agentskills.io) support for Laravel AI. Load, register, and wire skill-based instructions and tools into your AI agents.

Installation

composer require truthanb/laravel-ai-skills

Quick Start

1. Create a Skill Directory

Create a skill directory with a SKILL.md file following the Agent Skills specification:

resources/skills/
└── customer-support/
    ├── SKILL.md
    ├── scripts/
    │   └── triage.sh
    └── references/
        └── TEMPLATES.md

The SKILL.md file uses YAML frontmatter:

---
name: customer-support
description: Handle customer support inquiries and ticket routing.
license: MIT
---

# Customer Support Skill

Use this skill when handling customer inquiries...

2. Use the HasSkills Trait

Add the HasSkills trait to your agent and call skillPrompt() in your instructions and skillTools() in your tools:

<?php

namespace App\Agents;

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;
use Truthanb\LaravelAiSkills\HasSkills;

class SupportAgent implements Agent, HasTools
{
    use HasSkills, Promptable;

    public function instructions(): string
    {
        return 'You are a helpful support assistant.'.$this->skillPrompt();
    }

    public function tools(): iterable
    {
        return [...$this->skillTools()];
    }
}

By default, skills are loaded from resources/skills/ — following Laravel conventions. You can publish the config to customize the path. The agent automatically gets:

• Skill descriptions injected into its system prompt (via skillPrompt())
• activate_skill tool to load full skill instructions on demand
• read_skill_resource tool to read scripts, references, and assets from a skill

Configuration

Publish the config file to customize skill paths:

php artisan vendor:publish --tag=skills-config

This creates config/skills.php where you can set your paths:

return [
    'paths' => [
        resource_path('skills'),
    ],
];

Custom Skill Paths Per Agent

Override skillPaths() on a specific agent to load skills from different directories:

class SupportAgent implements Agent, HasTools
{
    use HasSkills, Promptable;

    public function instructions(): string
    {
        return 'You are a helpful assistant.'.$this->skillPrompt();
    }

    public function tools(): iterable
    {
        return [...$this->skillTools()];
    }

    protected function skillPaths(): array
    {
        return [
            resource_path('skills/support'),
            resource_path('skills/shared'),
        ];
    }
}

Direct Override (DB, S3, etc.)

For skills loaded from a database, S3, or any non-filesystem source, override skills() directly:

class DynamicAgent implements Agent, HasTools
{
    use HasSkills, Promptable;

    public function __construct(protected array $loadedSkills = []) {}

    public function instructions(): string
    {
        return 'You are a helpful assistant.'.$this->skillPrompt();
    }

    public function tools(): iterable
    {
        return [...$this->skillTools()];
    }

    public function skills(): array
    {
        return $this->loadedSkills;
    }
}

Manual Approach

If you prefer full control, manage the SkillRegistry and tools yourself:

use Truthanb\LaravelAiSkills\ActivateSkillTool;
use Truthanb\LaravelAiSkills\ReadSkillResourceTool;
use Truthanb\LaravelAiSkills\SkillRegistry;

class ManualAgent implements Agent, HasTools
{
    use Promptable;

    public function __construct(protected SkillRegistry $skills) {}

    public function instructions(): string
    {
        $instructions = 'You are a helpful assistant.';

        if ($this->skills->count() > 0) {
            $instructions .= "\n\n".$this->skills->toPrompt();
        }

        return $instructions;
    }

    public function tools(): iterable
    {
        return [
            new ActivateSkillTool($this->skills),
            new ReadSkillResourceTool($this->skills),
        ];
    }
}

Caching

Skills are automatically cached using Laravel's cache system (default TTL: 1 hour). If caching is unavailable, skills are loaded directly from the filesystem with a graceful fallback.

Override skillCacheTtl() to customize:

protected function skillCacheTtl(): int
{
    return 1800; // 30 minutes
}

Call clearSkillCache() to reset both in-memory and persistent caches:

$agent->clearSkillCache();

Specification

This package follows the Agent Skills specification. Each skill is a directory containing a SKILL.md file with YAML frontmatter and optional resource subdirectories (scripts/, references/, assets/).

License

MIT