Scramble × Laravel Boost

Published October 4, 2026

Scramble's Laravel Boost skill guides agents to keep your code as the source of truth for API documentation and verify the generated spec.

An agent can add API documentation and accidentally make it stop following your code. It only takes a few unnecessary type overrides.

I’ve added Laravel Boost integration to guide agents to keep your code as the source of truth for your docs, and give them a quick way to check their work.

It feels overdue, but only recently did I understand how I wanted it to work. Even without an integration, an agent can install Scramble and add attributes here and there. In my testing, agents often do that even when Scramble can already infer the same information. You get documentation, but also another contract to maintain.

I wanted the integration to teach agents how I believe Scramble should be used: let the application code describe the API, then verify what Scramble generates from it.

How an unnecessary annotation causes drift

Scramble generates OpenAPI documentation from your routes, validation rules, resources, model types, and other application code. When that code changes, the documentation can change with it.

Consider a controller that returns a user’s ID and name. If you ask an agent to add API documentation to such an endpoint, most likely it will add a response attribute that repeats the response shape:

use App\Models\User;
use Dedoc\Scramble\Attributes\Response;

#[Response(200, type: 'array{id: int, name: string}')]
public function show(User $user): array
{
    return [
        'id' => $user->id,
        'name' => $user->name,
    ];
}

That annotation adds no information because Scramble can resolve the model’s attribute types. It overrides a response shape that Scramble could infer from the return value.

Later, you add an email field to the response. The application returns it, but the manual response type still describes only id and name. You now have to remember to update both.

use App\Models\User;
use Dedoc\Scramble\Attributes\Response;

#[Response(200, type: 'array{id: int, name: string}')]
public function show(User $user): array
{
    return [
        'id' => $user->id,
        'name' => $user->name,
        'email' => $user->email,
    ];
}

The response attribute still overrides inference, so the generated documentation omits email even though the application returns it.

Scramble’s Boost skill guides agents to prefer inference, add missing type information, and use narrow overrides only where inference cannot supply the correct documentation.

Attributes still have a place. But every duplicated type is another opportunity for the documentation to drift.

Give the agent a way to check its work

Instructions alone are not enough. An agent needs to see the generated documentation and get useful feedback about problems.

For a named endpoint, the skill guides it to run a scoped export. If the route is named users.show, that looks like this:

php artisan scramble:export \
  --routes=users.show \
  --stdout \
  --fail-on-unknown

This gives the agent three things:

• --routes limits generation to those named routes within the configured API selection.
• --stdout writes the OpenAPI JSON directly to stdout, so the agent can read it without creating a temporary file. Diagnostics go to stderr.
• --fail-on-unknown reports unknown schemas as errors and returns a nonzero exit code when they occur. The generated JSON is still available to inspect.

Export now includes full diagnostics by default, without needing --verbose. Depending on the issue, these include route or class context, source locations, code snippets, and tips for fixing it.

The agent can inspect the spec, follow a diagnostic back to the source, make a fix, and repeat the export. That feedback loop was the other thing I wanted from the integration: agents should see documentation problems while they are working on the code.

This matters more as an API grows. A full OpenAPI document can be several megabytes. Reading all of it to verify one endpoint fills the agent’s context with information it does not need. A scoped export keeps the feedback relevant to the change.

Both scramble:export and scramble:analyze accept --routes.

A green exit code is only the beginning

The command can succeed even when the documentation is wrong.

The skill tells agents to confirm that the expected methods and paths appear, then inspect request parameters, status codes, response schemas, referenced components, and authentication. That includes details such as whether fields are required, optional, or nullable, and whether resource wrapping and pagination are represented correctly.

An unmatched route name can produce an empty export with a successful exit code. And the stale response attribute above contains no unknown types: --fail-on-unknown cannot tell you that email is missing. The agent needs to compare the generated spec with the application code.

When a change affects a shared resource or validation rule, the skill also guides the agent to check other affected endpoints.

Make route-selection problems visible

Another common problem happens before there is any schema to inspect: Scramble selects no API routes.

By default, Scramble selects routes under api. Applications with a different route structure may need configuration. An agent can mistake an empty document for a successful setup.

The updated analysis command makes that easier to catch:

php artisan scramble:analyze --fail-on-empty --fail-on-unknown

It reports how many routes matched and how many OpenAPI operations they produced. It also explains the selection rule: included and excluded paths, domain restrictions, or the source location of a custom routes() matcher.

--fail-on-empty makes analysis fail when the generated document has no paths. The skill guides the agent to investigate route selection and fix the appropriate configuration, then verify an expected endpoint in the export.

If the application has no API routes yet, an empty document is expected. The skill accounts for that too: it tells agents not to add routes or broaden matching just to make the check pass.

Remove annotations when inference makes them unnecessary

Scramble’s inference improves as features are added and bugs are fixed. An annotation that once supplied missing information can eventually become redundant.

The PD001 diagnostic detects redundant @var annotations on array items. For example, when Scramble can infer name as string from the model’s attribute type, this annotation repeats information it already has, so the agent can remove it:

public function toArray(Request $request): array
{
    return [
        /** @var string */
        'name' => $this->name,
    ];
}

Scramble reports PD001 with the tip: “Remove @var; the type is already inferred as string”. It gives agents concrete feedback about where they can let inference take over.

Give it a try

The command examples above require Scramble 0.13.46 or later. If you already use Scramble and a version of Laravel Boost that supports Agent Skills, run:

php artisan boost:install

Enable guidelines and Agent Skills during installation so Boost can discover Scramble’s integration. Boost installs package skills based on your preferences; see the Laravel Boost documentation.

Give it a try and let me know how it works for you.