AI-assisted development

With Scramble, your Laravel code is the API contract. Validation rules, API Resources, PHP types, middleware, and routes determine the generated OpenAPI document.

Agents often respond to documentation tasks by adding attributes or PHPDoc that repeat what Scramble already knows. When a manual schema replaces inference, later changes to your application types no longer flow into the documentation. You are left maintaining two contracts that can drift apart.

Scramble’s Laravel Boost integration teaches agents to keep application types precise and let Scramble infer from them. Manual documentation still has a place for information the code cannot express, such as descriptions, examples, or genuinely unresolvable types. It should fill a gap instead of restating the source code.

From assumption to verification

Writing plausible Laravel code is not enough to know that the resulting API documentation is correct. The Scramble skill gives the agent a workflow for evaluating the generated OpenAPI document with Scramble’s built-in commands.

The command workflow below requires Scramble 0.13.46 or later.

After changing an endpoint, the agent can export only the affected named routes:

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

With --stdout, the OpenAPI JSON goes to stdout and diagnostics go to stderr. Keep the streams separate and inspect both. --fail-on-unknown returns a nonzero exit code when unknown schemas are found, but the generated JSON is still available to inspect.

It then checks the actual request parameters, response schemas, status codes, resource wrapping, pagination, and authentication requirements. It also reads Scramble’s diagnostics instead of treating a successful command as proof that the contract is accurate.

For API-wide work, the agent can start with diagnostics without loading a large OpenAPI document:

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

This creates a useful feedback loop: change the application code, generate its contract, inspect the result, and correct the source of any mismatch. The agent does not have to assume what Scramble inferred.

Check route selection

When the application has API routes that should be documented, also check for an empty document:

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

--fail-on-empty makes analysis fail when the generated document has no paths. Analysis reports the matched route count, operation count, and route-selection configuration. If no routes match, check the selected API, path and domain filters, custom route matcher, and exclusions before changing schemas.

This check confirms that some paths exist; it does not confirm that a particular endpoint was selected. Verify expected methods and paths in the export too.

If the application has no API routes yet, omit --fail-on-empty. An empty document is expected in that case.

Remove redundant annotations

The PD001 diagnostic identifies redundant @var annotations on array items. When Scramble already infers name as string from the model’s attribute type, the annotation can be removed:

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

The diagnostic includes the tip: “Remove @var; the type is already inferred as string”. After removing the annotation, repeat the export to verify the generated schema.

Install Laravel Boost

Install Boost as a development dependency in your Laravel application:

composer require laravel/boost --dev

Then run the interactive installer:

php artisan boost:install

Select the agents you use and enable both guidelines and Agent Skills when prompted. Boost detects dedoc/scramble in your application and installs Scramble’s resources alongside the guidance for Laravel and your other supported packages.

If you already use Boost, rerun php artisan boost:install and enable Agent Skills to discover Scramble’s integration.

What the Scramble skill provides

The scramble-development skill teaches your agent to:

• preserve validation rules, API Resources, model casts, return types, and concrete values as the source of the API schema;
• avoid attributes and PHPDoc that merely repeat information Scramble already infers;
• add manual documentation narrowly when information cannot be expressed or resolved from application code;
• inspect routes and existing Scramble configuration before making changes;
• verify affected endpoints against a focused OpenAPI export;
• read Scramble diagnostics before changing application code;
• distinguish missing type information from a Scramble limitation or likely bug;
• choose the narrowest appropriate fix, such as improving a PHP type, adding a focused attribute, or creating an extension.

Using the skill

Ask your agent to work on the API as you normally would. Agents that support skills can load scramble-development automatically when the task involves Scramble or an API contract. You can also name the skill explicitly:

Using the scramble-development skill, add an endpoint for updating a user’s profile and verify its generated OpenAPI documentation.

Keep the guidance up to date

After updating Scramble or Laravel Boost, refresh the generated guidelines and installed skills:

php artisan boost:update

Use --discover to let Boost check for newly available guidelines and skills:

php artisan boost:update --discover

See Laravel’s AI-assisted development documentation for supported agents and the rest of the Boost workflow.