Guide · Agent skill

How to use the Laravel TDD Workflow agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The laravel-tdd skill is a set of written instructions that teaches an AI agent to build Laravel applications test-first: write a failing test, make the smallest change that passes it, then tidy the code. It is written for PHP developers who maintain Laravel APIs or web apps and want consistent tests. After this guide you will know how to install the skill, how to ask for it in plain language, and what to check before you rely on its output.

Laravel TDD Workflowaffaan-m/ECC · MIT Download the skill

Quick start

1Download the ZIP. Download the laravel-tdd skill ZIP from this page.
2Install the skill. Unzip it into ~/.claude/skills/ for all projects, or into the project's .claude/skills/ folder. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills instead.
3Prepare the Laravel project. Confirm PHPUnit or Pest is installed via Composer and that you have a working test runner.
4Set up a test database. Configure phpunit.xml to use SQLite in memory for fast, isolated tests, as the skill suggests.
5Ask for test-first work. Describe the feature, fix or refactor in plain language and ask for a failing test first.
6Review and run the tests. Check the tests the agent wrote, then run php artisan test, vendor/bin/phpunit or vendor/bin/pest yourself.

What the skill makes the agent do

The skill is documentation for the agent, not a program. It does not run anything by itself. When it is active, the agent follows its guidance on writing Laravel tests: which kind of test to write, how to reset the database between tests, when to prefer Pest over PHPUnit, and how to fake queues, mail, notifications and external HTTP calls.

Uses the red-green-refactor cycle: write a failing test, implement the minimal change, then refactor with tests passing.
Chooses a test layer: Unit for pure business logic and services, Feature for HTTP, authentication, validation and response shape, Integration when database, queues and external services are checked together.
Recommends RefreshDatabase by default, with DatabaseTransactions and DatabaseMigrations as alternatives.
Prefers Pest for new tests unless the project already standardises on PHPUnit.
Shows fakes such as Bus::fake(), Queue::fake(), Mail::fake(), Notification::fake(), Event::fake() and Http::fake().

Install the laravel-tdd skill

Download the skill ZIP from this page. The skill is a folder containing a file named SKILL.md. Unzip it into one of two places, depending on whether you want it for all projects or one project.

To make it available for all your projects, unzip it into ~/.claude/skills/. To make it available for a single project, unzip it into the project's .claude/skills/ folder. In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.

Personal (all projects): ~/.claude/skills/
Single project: .claude/skills/ inside the project folder
Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check what your Laravel project needs

The skill assumes a working Laravel project. Before you ask for test work, make sure PHPUnit or Pest is installed through Composer. The skill does not install these tools for you, and the agent still needs a working test runner.

If you want coverage reports, you need PHP with pcov or Xdebug. If you test API token authentication, the skill's examples use Laravel Sanctum, which is optional.

A Laravel project with PHPUnit or Pest installed via Composer
PHP with pcov or Xdebug, only if you want coverage reports
Laravel Sanctum, only if you test API token authentication

Trigger the skill with natural requests

You do not need a special command. Describe the work in plain language that touches the situations the skill covers: a new feature or endpoint, a bug fix, a refactor, or tests for models, policies, jobs or notifications. The agent can then load the skill's guidance.

Name the outcome you want. Say which layer you expect and whether the project uses Pest or PHPUnit if you know. Clear requests produce clearer tests.

"Add a test first for the new endpoint that lists a user's projects, then implement it."
"Fix the bug where archived projects still appear in the index. Write a failing test before changing the code."
"Write Pest feature tests for the invoice notification and fake the mail."
"Test the update policy for projects with an admin user and a non-owner."

Example: the kind of tests the skill writes

The skill includes examples in both frameworks. A typical Pest feature test creates a user with a factory, sends a request as that user, then checks the status and the database. The skill's Pest example for creating a project looks like this.

use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;

use function Pest\Laravel\actingAs;
use function Pest\Laravel\assertDatabaseHas;

uses(RefreshDatabase::class);

test('owner can create project', function () {
    $user = User::factory()->create();

    $response = actingAs($user)->postJson('/api/projects', [
        'name' => 'New Project',
    ]);

    $response->assertCreated();
    assertDatabaseHas('projects', ['name' => 'New Project']);
});

Use fakes for side effects

Jobs, queues, mail, notifications and outgoing HTTP calls can make tests slow or affect real systems. The skill tells the agent to replace them with fakes and then assert that the expected thing was dispatched or sent. The skill's queue example is shown below.

Bus::fake() for jobs, Queue::fake() for queued work, Mail::fake() and Notification::fake() for notifications, Event::fake() for domain events
Http::fake() to isolate external APIs and Http::assertSent() to verify outgoing payloads

use Illuminate\Support\Facades\Queue;

Queue::fake();

dispatch(new SendOrderConfirmation($order->id));

Queue::assertPushed(SendOrderConfirmation::class);

Safety notes: scripts and network

According to the skill's listing, it runs no scripts and uses no network access. It is written guidance only. Any commands that run, such as php artisan test, vendor/bin/phpunit or vendor/bin/pest, are run by your agent and tools in your own project, so review what the agent executes before approving it.

The skill suggests a separate testing environment so tests do not touch development or production data. A common setup described in the source is phpunit.xml with DB_CONNECTION=sqlite and DB_DATABASE=:memory:. Check that your phpunit.xml is set up this way before running tests against a real project.

No scripts are run by the skill itself.
No network use is declared by the skill.
Keep tests on a separate environment from development and production data.

What people use it for

Adding a new API endpoint with a feature test that checks status codes and JSON structure.
Fixing a bug by writing a failing test that reproduces it before changing the code.
Testing Eloquent model behaviour, policies and authorisation with Gate checks.
Writing tests for queued jobs and notifications using fakes instead of real sends.
Checking Inertia page components and props in dashboard feature tests.

Frequently asked questions

How do I install the laravel-tdd skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project. In the Claude apps you can upload the ZIP under Settings → Capabilities → Skills.

What does a Laravel project need to use this skill?

You need a Laravel project with PHPUnit or Pest installed through Composer. PHP with pcov or Xdebug is needed only for coverage reports, and Laravel Sanctum is optional for testing API token authentication.

Is the laravel-tdd skill free?

The skill is listed under the MIT licence. Check the licence file in the source repository for the full terms.

Does the skill run my tests automatically?

No. The skill is written instructions for the agent and does not run anything by itself. The agent still needs a working Laravel project and test runner, and commands such as php artisan test are run through your agent in your project.

Can I use this skill with Laravel packages or non-Laravel PHP projects?

The skill is aimed at Laravel. Its examples and advice rely on Laravel's testing helpers, so it is not suited to non-PHP projects or non-Laravel projects.

Should I use Pest or PHPUnit with this skill?

The skill recommends Pest for new tests when it is available. It suggests PHPUnit only if the project already standardises on it or needs PHPUnit-specific tools.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you build or maintain Laravel APIs or web apps and want an AI agent to add tests alongside new features and bug fixes in a consistent way. Pick something else if your project is not Laravel, or if you expect the skill to run tests or install tools for you. If the skill's 80% coverage target or database strategy conflicts with your existing conventions, adapt the guidance before you use it.

Download the skill