tomevault-io 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-kitis installed via Composer- Base
Controlleralready uses theApiResponsetrait - 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 toidif 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/(orRepositories/) - DTOs:
app/Domain/{Domain}/DTO/(orDTOs/) - 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:
- Add the override to your project's AI instructions file (e.g.
AGENTS.md,CLAUDE.md, or.claude/rules/for Claude Code). - 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 readonlypromotion - 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 scratchworkflows/add-filter.md— add filtering to an existing modelworkflows/write-tests.md— write tests for any feature (decides test type, structure, actors, edge cases)
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 filesworkflows/organize-knowledge.md— consolidate scattered docs into one-file-per-featureworkflows/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.
Source: ahmedesa/laravel-api-tool-kit — distributed by TomeVault.