Laravel API Architecture Skill

Install

npx skills add streeboga/laravel-api-skill

This is third-party code. Review the repository files before installing.

What it does

The skill defines a Controller, Service, Repository, QueryBuilder, Model chain with clear layer boundaries. When asked for a new entity, the agent generates 14 files: migration, model with ULID keys, enums, Spatie Data DTOs, FormRequests, QueryBuilder, repository, service, controller, JsonApiResource, routes and feature tests. On first use it creates or extends the project CLAUDE.md so the rules apply every session. Per-layer references load only for the current task.

Who it is for. For PHP developers and teams building Laravel APIs who want consistent agent-written code.

Example request

Create an Invoice entity with CRUD endpoints, status filtering and tests

Limitations

Requires PHP 8.2+, Laravel 10+ and a specific package set: timacdonald/json-api, spatie/laravel-query-builder, spatie/laravel-data and others. The architecture is strict, for example model scopes are forbidden. The skill edits the project root CLAUDE.md itself.

How to disable. Remove the laravel-api skill from the skills directory and delete the Laravel architecture section from the project CLAUDE.md.

Security check

• The skill consists of instructions and templates
• Edits the project CLAUDE.md on first use

README in short

The README from the EQ Platform open source project describes a Laravel API skill installed via npx skills with automatic CLAUDE.md setup. It includes a layer boundary table, the 14 generated files, the reference structure and required packages. MUST DO and MUST NOT DO sections require strict types, final classes, at least 85% test coverage and no PHPStan baseline. Detailed workflows are in README.ru.md.

SKILL.md

---
name: laravel-api
description: "Laravel API architecture and code generation guide. JSON:API v1.1 spec compliant. Enforces layered architecture: Controller → Service → Repository → QueryBuilder. Uses timacdonald/json-api for resources, spatie/laravel-query-builder for filtering/sorting. Covers DTOs, Enums, public keys, Scramble docs, testing. MANDATORY TRIGGERS: Laravel API, REST API, JSON:API, создание API, архитектура Laravel, генерация CRUD, сервисный слой, репозиторий, DTO, API ресурс. Use this skill whenever the user works on a Laravel API project, creates new entities/endpoints, reviews Laravel code, or asks about Laravel API architecture patterns."
license: MIT
compatibility: "Requires PHP 8.2+, Laravel 10+, Composer"
metadata:
  author: streeboga
  version: "1.0"
---

# Laravel API Production-Ready Architecture (JSON:API v1.1)

## SETUP GATE (выполни перед любой работой)

При первом вызове этого скилла в проекте проверь CLAUDE.md в корне проекта:

1. Если файла CLAUDE.md нет — прочитай `templates/CLAUDE.md` из директории этого скилла и создай CLAUDE.md в корне проекта с его содержимым.
2. Если CLAUDE.md существует, но НЕ содержит секцию "## Архитектура (нарушение = баг)" — прочитай `templates/CLAUDE.md` и ДОПИШИ его содержимое в конец существующего CLAUDE.md.
3. Если секция уже есть — всё ок, продолжай работу.

---

This skill defines the architecture and code patterns for all Laravel API projects. Every new entity, endpoint, or feature must follow these rules.

## Core Architecture

```
HTTP Request → Route → Middleware → Controller → Service → Repository → QueryBuilder (scopes) → Model → DB
Response    ← JsonApiResource      ← Service   ← Repository ← QueryBuilder
```

### Strict Layer Boundaries (CRITICAL)

```
Controller ──→ Service ONLY (never Repository, never Model)
Service    ──→ Repository (never Model::query() directly)
Repository ──→ QueryBuilder + Model
```

**DB access policy:** Only Repository and QueryBuilder may touch the database. No `Model::query()`, `::create()`, `->save()`, `->delete()` in Controllers or Services.

Related