Agent Skills Laravel Package

Product Decisions This Supports

• Adoption / standardization decision: Whether to make alizharb/agent-skills the default AI-assisted development baseline across Laravel repos (starter templates, internal boilerplates, team onboarding docs). It converts ad-hoc "everyone prompts their own way" into a shared, versioned convention set.
• Build vs. buy (build vs. adopt): An alternative is hand-maintaining .cursor/rules, CLAUDE.md, Copilot instructions, and prompt snippets per repo. This package is essentially a curated, versioned bundle of that work — 62 skills + 44 guidelines + presets + a machine-readable manifest. The decision is "adopt/curate" vs. "write and maintain our own."
• Tooling/ecosystem bet: Committing to Laravel Boost and/or skills.sh as part of the dev workflow. This is a low-cost way to trial that ecosystem without a runtime commitment.
• Governance and AI-usage policy: The included safety guidance (prompt-injection resistance, dirty-worktree safety, AI-generated code review, security review) gives an internal AI policy concrete, enforceable artifacts in the repo rather than a wiki page nobody reads.
• Quality roadmap input: Skill coverage is a proxy for where AI-assisted work is expected to be risky or repetitive (Filament, Livewire, Inertia, API endpoints, webhooks, imports/exports, permissions, observability, releases). Useful when deciding which areas need reviewer checklists or additional guardrails.
• Onboarding and enablement: Presets (core, filament, api, saas, package, security, testing, frontend, devops) map cleanly to team archetypes, which makes a phased rollout (one preset per squad) straightforward.
• Metrics to watch post-adoption: PR rework rate on AI-assisted changes, review comment volume on convention/style issues, time-to-first-PR for new hires, and drift between generated code and house conventions.

When to Consider This Package

Consider adopting when:

• Your team uses AI coding assistants (Claude Code, Codex, Cursor, Windsurf, Copilot, or generic agents) as a daily part of Laravel development, not occasionally.
• You are on a modern stack — PHP 8.3+ and a Laravel version aligned with the package's targets. The skill and guideline content leans on current Laravel/PHP idioms; on materially older versions the guidance will drift from your reality.
• You already use, or are willing to pilot, Laravel Boost or skills.sh. The Boost-discoverable layout and manifest.json are the main structural differentiators versus a folder of loose markdown.
• You run multiple repos or squads where consistency of AI output matters more than bespoke per-team prompting.
• You want agent safety rails (prompt injection, dirty worktree, security and code-review skills) codified in-repo.
• You want low lock-in: it is a --dev dependency of Markdown and JSON. Fork, prune, or remove it in an afternoon.

Look elsewhere or defer when:

• No AI agents in the workflow. This package has no runtime behavior; it delivers zero value to teams not using assistants.
• You need runtime capability (validation, code generation, scaffolding). This is developer tooling only.
• You require vendor support or an SLA. v1.0.0, single-maintainer, young project — treat it as community tooling and plan to own your fork if it becomes load-bearing.
• You need deep customization now. Adopting means curating: deleting skills irrelevant to your stack, rewriting guidelines that conflict with house conventions. If nobody owns that curation, quality degrades quietly.
• Older Laravel/PHP baseline, or a non-Laravel PHP codebase. Content relevance drops sharply.
• Strict third-party content controls. It is auditable Markdown, so this is usually surmountable, but confirm the review process accepts externally sourced prompt content.

Adoption recommendation for v1.0.0: Pilot with the core preset in one repo and one squad for a sprint; measure review-comment volume on AI-assisted PRs before and after. Expand to filament/api/saas presets only if the pilot shows a reduction in convention-level rework. Pin the version — pre-1.x-adjacent ecosystem churn is the main practical risk.

How to Pitch It (Stakeholders)

For executives: This is a free, dev-only package that gives our AI coding assistants a shared rulebook for Laravel work. It costs nothing at runtime — it never ships to production — and can be removed in minutes. The upside is consistency: AI-generated code follows our conventions instead of each engineer's individual prompting style, with built-in guardrails around security review and agent safety. The risk is maintenance maturity, not operational risk: it is a young, single-maintainer project, so we should pilot it narrowly, pin the version, and be prepared to fork the Markdown if we standardize on it.

For engineering leadership: It bundles 62 Laravel-focused skills, 44 shared guidelines, and 9 curated presets, with Laravel Boost and skills.sh compatibility and out-of-the-box support for Claude Code, Codex, Cursor, Windsurf, and Copilot. It ships with validation and sync scripts plus CI (tests, Pint, PHPStan), and a manifest.json so tooling can discover skills programmatically. Integration is a composer require --dev and php artisan boost:install. Content is plain Markdown and JSON — fully auditable, forkable, and reversible, which keeps architectural lock-in near zero.

For engineering teams: Treat the skills as a starting library, not gospel. Curate the presets to your stack, delete what does not apply, and route disagreements back into the repo rather than into private prompts — that is where the leverage is. Watch the Laravel 13 / PHP 8.3+ orientation and prune any guidance that outpaces your actual version.