Overview

Introduction

You ask the agent to summarize a meeting note. It does it... in a slightly different format than last time. You ask again next week. Different format again. "Why won't you just stick to one shape?"

The answer is: because nothing told it to. Without explicit guidance, the model picks a reasonable structure each time, but "reasonable" varies turn to turn.

That's where skills come in. A skill is a reusable instruction set the agent can pull in on demand. Each skill is a folder holding a SKILL.md file: the folder name is the skill's name, the frontmatter describes when to use it, and the body is the prompt the agent follows when the skill is invoked.

Use skills for any task you want the agent to perform consistently:

• Summarizing meeting notes in a specific layout
• Drafting an email reply in your voice
• Generating release notes from a list of commits
• Reviewing code with a fixed checklist

Write the prompt once, let the agent pick it up. Let's see how.

Where Skills Live

Skills are stored on disk under the path configured by LARACLAW_SKILLS_PATH, which defaults to laraclaw/skills/ at the root of your Laravel project.

Each skill lives in its own directory, with a single SKILL.md file inside:

laraclaw/
  skills/
    greeting/
      SKILL.md
    summarize/
      SKILL.md
    release-notes/
      SKILL.md
      reference.md
      scripts/build.sh

The directory name is the skill name. Rename the folder to rename the skill. A name key in the frontmatter is ignored, so the name you see in the tree is always the name the agent calls.

Skill File Format

---
description: Condense a long passage into 3 bullet points.
---

You are a text summarizer. When called, take the provided text and produce
exactly 3 concise bullet points. Each bullet should be a complete sentence and
should not start with the same word as another bullet. Do not include any
other commentary.

Two parts matter:

• description — what the agent reads when deciding whether the skill is relevant. This is a routing hint, not a label. Describe the job that should trigger the skill, not what the file is. Generate release notes from a list of git commits gets picked up; Release notes skill does not.
• The body — the actual instructions the agent follows when it invokes the skill.

Leave the description out and Laraclaw falls back to the first line of the body and logs a warning. The skill still loads; it is just advertised badly.

Companion Files

Anything else in the skill folder rides along. Reference material, SQL, templates, shell scripts:

laraclaw/skills/release-notes/
  SKILL.md
  reference.md
  scripts/build.sh

When the agent loads a skill it is told the folder's absolute path and what is in it, so SKILL.md can say "run scripts/build.sh" or "the column definitions are in reference.md" and the agent can actually go and get them.

Keeping the long reference material in a separate file is usually the right move: only SKILL.md is pulled into context when the skill loads, so the extras cost nothing until something actually reads them.

How the Agent Discovers Skills

The SkillRegistry is a singleton. The first time it's resolved in a process, it scans the skills directory and indexes every SKILL.md it finds. The UseSkill tool's description includes the name and description of each available skill, so the agent sees the full catalog without any manual registration.

In other words: drop a folder in, and it just shows up. No vendor:publish, no migration, no provider edits.

Publishing ships a small greeting skill so there is a working example on disk from day one. Delete it whenever you like.

!TIP Dropping a new file into the skills directory adds it the next time a fresh process picks it up. In production, that means restarting the queue worker after editing the skills directory. The terminal connector boots fresh per invocation, so it sees edits immediately.

Invoking a Skill

When the agent decides a skill applies, it calls the UseSkill tool with the skill name. The tool returns the body of the SKILL.md file, which the agent follows as additional instructions for its current turn.

You can also nudge the agent in chat:

"Use the summarize skill on this article: ..."

The agent will read the summarize skill's body and follow it.

What's Next

• Adding Custom Skills — the workflow for writing a skill that the agent will actually pick up reliably.
• Personas vs Skills — both are Markdown files, but they do very different things. Personas change how the agent talks across a whole thread; skills are reusable procedures the agent calls when needed.

Until next time!