Agent Skills Laravel Package

Getting Started

• Install as a dev-only dependency: composer require alizharb/agent-skills --dev. The service provider is auto-discovered; you should not need to register anything manually.
• Register the skills with Laravel Boost (which must already be installed): php artisan boost:install. This makes Boost discover the package's skills under resources/boost/skills and the shared guideline at resources/boost/guidelines/core.blade.php.
• First place to look: vendor/alizharb/agent-skills/manifest.json. It is the machine-readable index of all 62 skills and 44 guidelines — ids, paths, descriptions. Use it as your map instead of guessing filenames.
• Second place: presets.json. Presets (core, filament, api, saas, package, security, testing, frontend, devops) tell you which skills are intended to be loaded together for a given project shape.
• Read one or two skill files end-to-end before trusting them. They are prose specifications, not code — calibrate the depth and conventions they assume against your own codebase.
• First realistic use case: pick the preset that matches the project, then hand the agent a normal task and watch whether it reaches for the matching skill. Example: with filament loaded, ask "add a Filament resource for Invoice with a policy and Pest feature test" and confirm the output follows the package's Filament, policy, and testing guidelines rather than generic Laravel patterns.

Implementation Patterns

Preset-scoped loading. Don't dump all 62 skills into context. Select the preset(s) that match the project — api + testing for a JSON backend, filament + saas for an admin app, package for a library repo — and only add individual skills on demand. This keeps the agent's context budget on the instructions that matter for the current task.

Layer team guidelines on top of the package. The package's guidelines are a baseline; your house rules (naming, folder layout, PR conventions) should live in your own guideline files and be loaded after the package's so they take precedence when the agent sees a conflict. Keep them short — the package already covers a lot of surface.

Use the manifest for tooling, not just reading. manifest.json is stable and machine-readable, so it is reasonable to build small internal helpers on it: a linter that checks every skill you reference in docs actually exists, a generator that emits a CLAUDE.md / .cursor/rules / Copilot instructions file from a chosen preset, or a script that lists skills by tag.

Non-Boost agents. For Claude Code, Codex, Cursor, Windsurf, Copilot, and skills.sh consumers, the package ships a root skills/ directory plus per-tool documentation. The pragmatic pattern is symlinking or copying the chosen skill files into the tool's expected location (.cursor/rules, CLAUDE.md, etc.) rather than asking developers to remember which directory each tool reads. If you copy, copy a subset derived from a preset, not the whole tree.

Keep the two skill trees in sync. skills/ (skills.sh) and resources/boost/skills/ (Boost) are separate directories. If you fork or author skills locally, use scripts/sync-boost-skills.php to propagate changes rather than hand-editing both.

Regenerate the manifest in CI. scripts/generate-manifest.php should run whenever skills change, and scripts/validate-skills.php should gate the build. Wire both into composer.json scripts (e.g. composer validate-skills) so they run identically on a laptop and in GitHub Actions.

Pull guidelines into review workflows. Several skills are explicitly review-oriented (security review, accessibility review, AI-generated code review, PHPStan debugging). The useful pattern is not just "let the agent write code" but "run the agent as a reviewer with the relevant skill loaded" — e.g. before merging, ask the agent to review the diff against the security and accessibility guidelines.

Pin the version. Skills are content, and content changes behavior. Commit composer.lock and treat a package bump like a prompt change: review the changelog diff before letting it apply across the team.

Gotchas and Tips

• --dev is not optional in spirit. This package ships markdown, not runtime code. Installing it without --dev bloats production installs for zero benefit.
• Context bloat is the main failure mode. 62 skills plus 44 guidelines is far more text than any agent should carry at once. If output quality degrades or the agent starts ignoring instructions, the cause is almost always "too many skills loaded", not "the skills are wrong". Cut to one or two presets first.
• Skills are guidance, not enforcement. Nothing here prevents a model from writing a fat controller. Treat the skills as a strong default and keep your existing static analysis (PHPStan, Pint) as the actual gate.
• Two source-of-truth directories. skills/ and resources/boost/skills/ can drift silently. Run scripts/validate-skills.php locally before opening a PR, and in CI on every push.
• Manifest drift. Adding or renaming a skill without running scripts/generate-manifest.php leaves manifest.json stale, and any tooling you built on it will silently miss the new skill. Make regeneration part of the skill-authoring checklist.
• Preset names are exact keys. A typo in a preset reference (e.g. frontend vs front-end) will not raise a helpful error — it will simply load nothing. Verify against presets.json when wiring a custom loader.
• Boost version matters. boost:install behavior and the expected skill directory layout are tied to the installed Boost version. If skills don't appear after install, check Boost is present and current before debugging the package.
• The Blade guideline is a Blade file. resources/boost/guidelines/core.blade.php is processed as a template. If you edit it, syntax errors surface as rendering failures, not obviously as guideline failures.
• Non-Boost setup is manual by design. There is no artisan command to wire skills into Cursor/Codex/Copilot. Budget time for the first setup per tool, and check in whatever wiring you use (symlink script, generated files) so new team members don't repeat it.
• Safety skills are advisory. The prompt-injection resistance and dirty-worktree guidelines are text instructions to the model. They are a useful nudge, not a sandbox — keep real guardrails (worktree checks, command approvals, read-only tokens) in place.
• Debugging tip: if the agent suddenly ignores a guideline, grep the skill text for the exact phrase you expect it to follow. If the phrase isn't there, the guideline didn't load — check the preset and Boost discovery rather than rewriting your prompt.
• Extension point: authoring your own skills is the intended escape hatch. Follow the existing file structure, add the entry to manifest.json via the generator, and validate — do not fork the package for one team-specific rule.