Laravel Agent Skills

Composable agent skills for real Laravel engineering — not vibe coding. Small, adaptable practices you can mix into any project. Works with OpenCode, Claude Code, Cursor, Codex, and other agents.

Forked from mattpocock/skills and adapted for PHP, Pest, Pint, and Laravel conventions.

Quickstart

OpenCode

OpenCode discovers skills from ~/.config/opencode/skills/ (global) and .agents/skills/ in a project. This repo includes a local plugin that wraps the install scripts as tools.

# Install skills globally for OpenCode (and Claude / Agents)
./scripts/link-skills.sh opencode
# Or all targets:
./scripts/link-skills.sh

# Install into a Laravel project's .agents/skills/
./scripts/link-skills.sh --project /path/to/your-app opencode

When you open this repository in OpenCode, .opencode/plugins/laravel-skills.ts loads automatically and exposes link_skills and list_skills tools (same behaviour as the bash scripts). OpenCode runs bun install in .opencode/ on startup for @opencode-ai/plugin.

See OpenCode skills and plugins.

Claude Code

./scripts/link-skills.sh claude

Or use .claude-plugin/plugin.json with the Claude plugin installer.

Other agents

./scripts/link-skills.sh agents   # ~/.agents/skills (also read by OpenCode)
./scripts/list-skills.sh          # list SKILL.md paths in this repo

Laravel project setup

1. Run /setup-laravel-skills once per Laravel repo. It records:

   • Issue tracker (GitHub, GitLab, or local markdown)
   • Triage label vocabulary
   • Domain doc layout (CONTEXT.md, docs/adr/)
   • Laravel stack (Pest vs PHPUnit, Blade/Livewire/Inertia, Pint, PHPStan, dev environment)

2. Use the skills that match your workflow — /grill-with-docs before big changes, /tdd for features, /diagnose for hard bugs.

Why these skills exist

Same failure modes as any agent-assisted project — misalignment, verbose jargon, weak feedback loops, and fast-growing complexity. These skills encode fundamentals:

Problem	Skill
Agent didn't understand what you want	/grill-me, /grill-with-docs
Agent uses the wrong vocabulary	/grill-with-docs → CONTEXT.md
Code doesn't work / no feedback	/tdd, /diagnose
Ball of mud	/improve-codebase-architecture, /zoom-out

Shared language example

Before: "There's a problem when a lesson inside a section of a course is made real in the filesystem."

After: "There's a problem with the materialization cascade."

Define terms once in CONTEXT.md; agents and humans stay aligned.

Laravel feedback loops

• Static analysis — PHPStan / Larastan
• Format — Pint
• Tests — Pest Feature tests through HTTP, unit tests on Actions
• Fakes — Http::fake(), Queue::fake(), Mail::fake()
• Local run — Sail, Herd, or php artisan serve

The /tdd skill enforces red-green-refactor with vertical slices — one failing Pest test, minimal implementation, repeat.

Reference

Engineering

• diagnose — Reproduce → minimise → hypothesise → instrument → fix → regression-test.
• grill-with-docs — Grilling session + CONTEXT.md + ADRs.
• triage — Issue triage state machine.
• improve-codebase-architecture — Deepening opportunities using domain language and ADRs.
• setup-laravel-skills — Per-repo config: issue tracker, triage labels, domain docs, Laravel stack. Run first.
• tdd — TDD with Pest/PHPUnit; integration-style tests through HTTP and Actions.
• to-issues — Break plans into vertical-slice issues.
• to-prd — Synthesise conversation into a PRD on the issue tracker.
• zoom-out — Higher-level context on unfamiliar code.
• prototype — Artisan logic simulator or multi-variant UI (Blade / Livewire / Inertia).

Productivity

• caveman — Ultra-compressed communication mode.
• grill-me — Interview until the decision tree is resolved.
• handoff — Compact handoff for the next agent session.
• write-a-skill — Author new skills with proper structure.

Misc

• git-guardrails-claude-code — Block dangerous git commands via Claude hooks.
• setup-laravel-git-hooks — Pre-commit: Pint + Pest + optional PHPStan (no Node).

Buckets

See AGENTS.md for how skills are organised (engineering/, productivity/, misc/, personal/, in-progress/, deprecated/).

Personal, in-progress, and deprecated buckets are unchanged from upstream (not listed in README).