Laravel API Tool Kit Skill

This project uses the essa/api-tool-kit package. All API code MUST follow the standards in this skill — both the general Laravel best practices and the package-specific patterns.

Assumed Setup

• essa/api-tool-kit is installed via Composer
• Base Controller already uses the ApiResponse trait
• The dateTimeFormat() global helper is available
• dynamicPaginate() macro is registered on the query builder

Project Defaults

Fill these in when installing the skill. The AI reads this section to match existing project conventions.

• Primary key type: ulid ← change to id if this project uses auto-increment
• Auth guard: sanctum ← change if different (e.g. api)
• Test class: Tests\TestCase ← change if the project uses a custom base

Structure Mapping & Customization

The rules in the rules/ directory are pattern-based. While examples use standard Laravel paths (e.g., app/Models), they are designed to be mapped to any structure.

DDD / Domain-Driven Design

If the project uses a DDD structure, the rules apply to the corresponding domain folders. Folder naming may vary by project (e.g., Repository vs Repositories). Examples include:

• Models: app/Domain/{Domain}/Models/
• Actions: app/Domain/{Domain}/Actions/
• Repositories: app/Domain/{Domain}/Repository/ (or Repositories/)
• DTOs: app/Domain/{Domain}/DTO/ (or DTOs/)
• Filters: app/Domain/{Domain}/Filters/

Note for AI: Always run ls app/Domain/ to identify the project's specific naming conventions before creating new files. Priority is always: Project Patterns > Global Rules.

Project-Specific Rules

If a specific project requires overrides (e.g., "We use id instead of ulid" or "We return raw arrays instead of DTOs"), do not modify these global rules. Instead:

1. Add the override to your project's AI instructions file (e.g. AGENTS.md, CLAUDE.md, or .claude/rules/ for Claude Code).
2. The AI will prioritize project-level instructions over these global patterns.

Baseline — Applies to Every File

Before reading anything else, these rules apply universally:

• Every PHP file MUST start with declare(strict_types=1);
• Every method MUST have parameter types and a return type
• Constructor dependencies MUST use private readonly promotion
• User-facing strings MUST use trans() — never hardcoded

See rules/code-quality.md for the full baseline.

Component Map

When working on a specific concern, read the corresponding rule file:

General Standards (applies everywhere)

Task	Read
Code style, types, naming, constants	rules/code-quality.md
Injecting dependencies	rules/dependency-injection.md
Events and listeners	rules/events.md
Standalone queued jobs	rules/jobs.md
Authorization and policies	rules/authorization.md
Error and exception handling	rules/exceptions.md
Writing feature tests	rules/testing.md
Database patterns, ULIDs, transactions, bulk ops	rules/database.md
External 3rd-party integrations	rules/services.md
DDD structure, domain boundaries, cross-domain rules	rules/ddd.md

Package-Specific Patterns

Task	Read
Return a JSON response	rules/responses.md
Add filtering / sorting / search to an endpoint	rules/filters.md
Create a new Action class	rules/actions.md
Create a DTO for an Action or Service	rules/dtos.md
Write or review a Controller	rules/controllers.md
Write a FormRequest	rules/requests.md
Write an API Resource	rules/resources.md
Create or update a Model	rules/models.md
Create or update a Repository	rules/repositories.md
Create an Enum	rules/enums.md
Add pagination	rules/pagination.md

Always Check First

Task	Read
Before writing any code	rules/anti-patterns.md

Building a New Endpoint

Follow workflows/new-endpoint.md for the full step-by-step process.

The order is always: Model → Migration → Filter → Enum → Requests → Resource → Policy → Action (if needed) → Controller → Language file → Route → Test

Available Workflows

Building

• workflows/new-endpoint.md — add a complete CRUD resource from scratch
• workflows/add-filter.md — add filtering to an existing model

Reviewing

• workflows/code-review.md — multi-phase code review (structural + defense + scope discipline)

Debugging

• workflows/investigate.md — structured debugging (data-first, multi-source, 15-min checkpoint)
• workflows/curl-test.md — test an endpoint with curl and cross-reference response vs DB

Knowledge Management

• workflows/update-knowledge.md — save learnings into rules or knowledge files
• workflows/organize-knowledge.md — consolidate scattered docs into one-file-per-feature
• workflows/create-workflow.md — capture a discovered process as a reusable workflow

Knowledge Base

Per-feature accumulated knowledge lives in a knowledge/ directory. The exact location depends on your AI tool:

• Claude Code: .claude/knowledge/[feature].md
• Antigravity: .agent/knowledge/[feature].md
• Cursor / Copilot: knowledge/[feature].md (project root)

Each file contains:

• Past issues and their confirmed root causes
• Reusable diagnostic queries (with placeholder variables)
• DB/data gotchas specific to this project
• Lessons that don't fit into general rules

When investigating a bug, check knowledge/ first. When confirming a root cause, update knowledge/ before closing the session.