Livewire v4 + Alpine.js — Agent Skills

Five Agent Skills that teach an AI coding
assistant Laravel Livewire v4 and Alpine.js v3 accurately — with complete
working recipes, a symptom-to-fix troubleshooting guide, version detection, and
the security half that Livewire's own defaults make easy to get wrong.

Works with Claude Code, Codex, Cursor, Gemini CLI, and anything else that reads
the SKILL.md format.

Written from the documentation, corrected by a production application. The
security half is not a reading of the docs. Alpine ships no security
documentation page at all, and Livewire's own defaults are what make its rules
easy to get wrong.

Those rules come from SeeRanks, a paid ranking board
being rebuilt on Laravel 13 + Livewire 4. Two of them were defects in that
codebase before they were rules here:

• six Alpine attributes interpolated server data into a JavaScript context.
  Blade escaped every one of them correctly, and the browser decoded the entity
  back before Alpine compiled the attribute.
• a wire:key published a table's integer primary keys. The test named
  after that leak asserted on "id":<n>, so it could not see the real shape —
  and a second test asserted the key was present, which pinned it in place.

The third is the persistent-middleware gap. permission: middleware does not
run again on the Livewire update endpoint, so a component behind it is not
behind it. That one was found by reading the framework, before it cost
anything.

Only SKILL.md enters context when a skill is invoked. The references/
files are read on demand through a routing table inside it, and bin/ is
executed rather than read. So the entry point is 514 lines, not 10,000 — the
depth is there when a task needs it and costs nothing when it does not.

The always-loaded cost is smaller still: an agent sees only each skill's
description, which is about 220 tokens for the largest of the five.

Renamed in 1.0.0. livewire-development → livewire-reference, and
alpinejs-development → alpinejs-reference. Laravel Boost ships its own
skill named livewire-development, and an identical name read as a
replacement for it; the Alpine rename follows for consistency. To update a
copy you installed:

rm -rf ~/.claude/skills/livewire-development ~/.claude/skills/alpinejs-development
cp -R livewire-reference alpinejs-reference livewire-security ~/.claude/skills/

No stub remains at either old name — a stub would restore the collision.
CHANGELOG.md has the rest.

Every badge above is a local measurement, not a CI run. This repository has
no GitHub Actions workflow. The self-test counts come from the commands in
Validation; run them yourself and the numbers should match.

Invoke livewire-reference for the stack. livewire-security is separate
because it is read at a different moment — before shipping a component on a
public route, or during a security review — and because most Livewire work does
not need it.

Invoke livewire-reference and you get both halves of the stack. Livewire bundles Alpine, so
real work touches both halves — bash bin/stack.sh finds the Alpine skill and
prints both file maps. They stay two skills because Alpine also runs with Rails,
Django and Hotwire.

Why these exist

Livewire v4 changed its defaults, and most model training data is v2 or v3.
An assistant left to its own knowledge will confidently write code that no longer
works. These are the twelve items the skill corrects before anything else:

Plus everything new in v4: islands, wire:sort, wire:intersect, wire:ref,
wire:bind, wire:text, #[Async], #[Json], #[Authorize], the automatic
data-loading and data-current attributes, the $errors magic, and
interceptors.

Use cases

What the skills are actually for. Each names the file that answers it.

Install

Claude Code

git clone https://github.com/olgunozoktas/livewire-alpine-skills.git /tmp/lw-skills
cp -R /tmp/lw-skills/livewire-reference  ~/.claude/skills/
cp -R /tmp/lw-skills/alpinejs-reference  ~/.claude/skills/
cp -R /tmp/lw-skills/livewire-security   ~/.claude/skills/
cp -R /tmp/lw-skills/livewire-performance ~/.claude/skills/
cp -R /tmp/lw-skills/alpinejs-security   ~/.claude/skills/

Per-project instead of global: copy into .claude/skills/ in the repo.

Restart the session. The assistant loads a skill on its own when the task
matches; /livewire-reference invokes it explicitly.

One invocation covers both

Livewire bundles Alpine, so real work touches both. From a Laravel project you
only need to invoke livewire-reference — it is the entry point for the
whole stack:

bash bin/stack.sh     # finds the Alpine skill and prints both file maps

It resolves the pairing in any layout (installed, this repo, or a source tree,
symlinks included) and shows which half answers which question. They stay two
skills because Alpine is also used with Rails, Django and Hotwire — invoke
alpinejs-reference directly for those.

Other agents

Copy the same two directories into whatever skills directory your tool reads —
.ai/skills/ for Laravel Boost, .codex/skills/, .cursor/skills/, and so on.

Using this alongside Laravel Boost

Boost ships its own Livewire skill, named livewire-development
(author: laravel), and installs it into .ai/skills/.

This skill used to carry that same name, and no longer does. An identical
name reads as a replacement for Boost's skill, which was never the intent. Boost
documents that a project-level skill of the same name overrides its built-in
one — so the old name did not break anything, it just said the wrong thing.

They are complementary — run both. Boost knows your Livewire version and
reads your config/livewire.php; it is deliberately terse because it is paired
with a live search-docs index. These skills are the depth behind it.

Side by side

Measured against laravel/boost's .ai/livewire/4/skill/livewire-development.

Boost wins on the bolded rows in its column, and those wins are structural.
It is a Composer package, so it knows your Livewire version, renders your real
paths, and updates itself. It is terse on purpose — it is paired with a live
documentation index, so it does not need to carry the depth.

These skills win on depth, on worked examples, on debugging, and on being
verified rather than asserted. Neither replaces the other.

Which to ask

If the two contradict each other on a fact, prefer the live docs and treat
this snapshot's date as the tiebreaker. bin/detect.sh warns when your project's
Livewire is newer than this skill's verification.

What's inside

livewire-reference

livewire-security

alpinejs-security

Alpine ships no security documentation page. Across its 56 doc pages,
security appears six times: a CSP page, and one XSS warning on x-html
repeated twice.

The gap that matters is not x-html, which is warned about clearly. It is that
an Alpine attribute is a JavaScript context, so a server template that
HTML-escapes into one has used the wrong encoder:

attacker display name : '+alert(document.cookie)+'
after Blade {{ }}     : '+alert(document.cookie)+'
what getAttribute sees: { name: ''+alert(document.cookie)+'' }

The browser decodes the entity before Alpine reads the attribute. Both the
attack and the @js() fix are verified against a real HTML parser.

bin/review-security.py carries 7 rules and stays silent on @js(),
Js::from(), data-* with $el.dataset, and Blade's own :prop="$var"
component bindings — that last one is the false positive that makes a checker
unusable.

livewire-performance

alpinejs-reference

The skill ships tools, not just text

Static text cannot know what your project does. These scripts read it:

bash bin/detect.sh                  # what does THIS project actually do?
bash bin/stack.sh                   # load BOTH halves — Livewire + Alpine
bash bin/scaffold.sh post.create    # create in the project's own conventions
python3 bin/review.py <file>        # v3-isms, security holes, known traps
bash bin/eval.sh --compare          # score code quality objectively

Alpine has its own reviewer too — alpinejs-reference/bin/review.py, 14
rules proven by 30 self-test cases, for v2-isms and the quiet traps (x-if off a <template>,
x-cloak with no CSS, a $watch that writes to what it watches).

Both are calibrated in two directions. Livewire: 9 errors on deliberately
v3-style code, 0 findings on the twelve verified recipes. Alpine: 7 errors on
v2-era markup, 0 on correct Livewire+Alpine. A checker that fires on correct
code is one people switch off.

--self-test proves every check still fires. It caught three bugs in the
Livewire reviewer's own rules — including one where the // in https:// was
parsed as a comment, so the duplicated-Alpine check could never fire — and two
false positives that only appeared when it was run against the verified
recipes.

Verified against v2 and v3 too

detect.sh and scaffold.sh are tested against real v2 and v3 project fixtures,
not only v4. On a v3 project scaffold.sh refuses --sfc, --mfc and
namespaces rather than emitting output that cannot work there, and detect.sh
warns when the project's Livewire is newer than this skill's verification.

Measured

$ bash bin/eval.sh --compare

  no skill (v3 habits)    46/100   errors:10  warns:2
  skill's recipes        100/100   errors:0   warns:0

  delta: +54 points

Both sides are fixed artifacts scored by the same deterministic rules — not
anyone's opinion.

The recipes are executed, not just written

Every component in references/recipes.md is rendered and exercised against a
real Livewire install:

cd livewire-reference && bash bin/verify-recipes.sh

It scaffolds a throwaway Laravel + Livewire 4 app, extracts each recipe into a
real component file, lints it, then renders it and exercises its actions with
Livewire::test(). No browser and no dev server — Livewire renders server-side,
so the whole suite runs in under a second.

Last run: 14 tests, 54 assertions, all passing on livewire v4.4.2 — a
release newer than the documented snapshot.

This is not ceremony. It found two defects that every text-level audit had
missed, because both fail at runtime rather than at review:

• the wizard defined public function reset(), silently overriding
  Livewire\Component::reset()
• four blocks called Auth::user() with no facade import — a fatal error

Validation

Every badge above is a number you can reproduce. There is no CI run behind them.

php     livewire-security/bin/scan.php          --self-test   # 22 checks
php     livewire-performance/bin/scan-performance.php --self-test # 13 checks
python3 alpinejs-security/bin/review-security.py    --self-test # 26 checks
php     livewire-security/bin/check-update.sh   --self-test   #  6 checks
python3 livewire-reference/bin/review.py        --self-test   # 53 checks
python3 alpinejs-reference/bin/review.py        --self-test   # 30 checks
#                                                              152 total

# Are the security skill's statements still true of the installed Livewire?
php     livewire-security/bin/verify-facts.php <laravel-app>    # 28 statements
python3 alpinejs-security/bin/verify-facts.py <path-to-alpine>   # 11 statements

# The recipe gate. Scaffolds a throwaway Laravel app and runs every recipe.
bash livewire-reference/bin/verify-recipes.sh                        # 14 tests, 54 assertions

# The update check, which must be able to speak AND stay silent.
bash livewire-security/bin/check-update.sh --self-test                # 6 checks

The first three need no network and no Laravel install. verify-facts.php needs
a project with livewire/livewire in vendor/. verify-recipes.sh needs
Composer, PHP and a temporary directory.

Staying current

cd livewire-reference && bash bin/refresh.sh

Re-clones both documentation sets, extracts the API surface, and reports
anything now documented that the skills do not mention. Read-only — it never
edits the skills. It carries an allowlist of verified noise, so a clean run
says CLEAN rather than crying wolf.

Provenance

Written from the primary sources, not from memory:

• Livewire — all 98 files in docs/ on the 4.x branch of
  livewire/livewire, commit 81f35ea.
  v3 differences read from the 3.x branch.
• Alpine — all 55 files in packages/docs/src/en of
  alpinejs/alpine. Version 3.16.3, which
  is what Livewire 4.x bundles.

Coverage is verified three ways:

1. API-surface diff — every directive, attribute, magic, global, component
   method, static, test assertion and lifecycle event extracted from both
   documentation trees and diffed against the skills. Clean.
2. Execution — every recipe rendered and exercised against a real Livewire
   install. 14 tests, 54 assertions, passing on v4.4.2.
3. An independent model — twelve high-risk claims fact-checked by Codex with
   the documentation excerpts supplied inline. 12/12 supported, 0
   contradicted.

Last audit 2026-08-26.

A few signatures the documentation omits (#[Authorize], #[Transition],
renderIsland(), streamIsland()) were read from the package source and are
labelled as source-derived where they appear.

Livewire moves. Run bin/refresh.sh, or check
livewire.laravel.com/docs/4.x, before
relying on anything version-sensitive in production.

Who maintains this

One person. Three products pay for the time, and the first one is why these
skills exist at all:

There is also a companion package for the other half of the problem these skills
describe: laravel-page-performance
measures what every Livewire page actually costs — snapshot bytes, repeated
queries with the file and line that ran them, per-component render timing — and
gates only on the counters that are deterministic. livewire-performance tells
an agent which fix matches which number; that package produces the number.

License

MIT — see LICENSE.

Content derived from the Livewire and Alpine.js documentation, both MIT licensed
and © Caleb Porzio and contributors.