HTMX Expert Skill v2

Stop building CRUD apps like it's 2018.

A modular, AI-optimized, production-grade HTMX skill for Claude, Cursor and Codex.

This skill enforces:

HTML-over-the-wire architecture
Server-driven UI
Fragment-based rendering
Correct swap strategies
Progressive enhancement
Security-first mindset
Anti-SPA discipline

If you are serious about HTMX, this is not optional.

Why This Exists

Most AI-generated HTMX code:

Returns JSON ❌
Rebuilds DOM manually ❌
Mimics React patterns ❌
Ignores swap strategies ❌
Breaks browser history ❌

This skill fixes that.

It forces AI to think like a server-driven architect.

What Makes This Different?

Unlike generic HTMX snippets, this skill:

✔ Enforces HTML-over-the-wire
✔ Prevents SPA anti-patterns
✔ Designs fragment architecture
✔ Uses OOB swaps correctly
✔ Handles validation properly
✔ Maintains browser history
✔ Mentions CSRF and security
✔ Includes production performance advice

This is opinionated on purpose.

Who Is This For?

SaaS founders
Backend-heavy teams
Internal tool builders
Admin panel developers
Teams migrating away from SPA
Engineers tired of unnecessary frontend complexity

Who Should NOT Use This?

Canvas-heavy apps
WebGL apps
Offline-first SPA
Complex client-side state apps

This skill is server-first.

Included

Modular skill layout: core rules (skill/skills.md), activation (skill/activation.md), reference docs (skill/reference/)
Reference: attributes, triggers, swap, events, server-patterns, validation, security, performance, headers, anti-patterns
Enterprise Strict Version (ENTERPRISE.SKILL.md)
Express + HTMX Production Demo
Real-world patterns
Anti-pattern enforcement
Test suite
Semantic versioning
Release workflow

Installation

For Cursor

Copy the skill files to your Cursor skills directory:
```
cp -r . ~/.cursor/skills/htmx-expert/
```
Or install via npm (when published):
```
npm install -g htmx-skill
```

For Codex

Copy the skill files to your Codex skills directory:
```
cp -r . $CODEX_HOME/skills/htmx-expert/
```

Usage

The skill automatically activates when you:

Use or ask about hx- attributes and HTMX patterns
Build server-driven UIs and CRUD with minimal JS
Work with HTML fragments, HX-Request, or partial templates
Migrate from React/Vue to HTMX or implement progressive enhancement

See skill/activation.md for full activation rules.

Example: Correct HTMX CRUD

Instead of:

fetch("/todos")
  .then(res => res.json())
  .then(data => buildDOM(data))

Do this:

<div id="todo-list" 
     hx-get="/todos"
     hx-trigger="load">
  <!-- Server returns HTML fragments -->
</div>

// Server returns HTML, not JSON
app.get('/todos', (req, res) => {
  res.render('_todo_list', { todos });
});

Quick Start

Run the Express Demo

cd examples/express-demo
npm install
npm start

Visit http://localhost:3000 to see HTMX in action.

Explore Patterns

Check out the pattern examples in examples/ (e.g. examples/express-demo/). For detailed attribute, swap, and server guidance see skill/reference/.

Project Structure

htmx-skill/
├── SKILL.md                 # Entry point → skill/skills.md
├── ENTERPRISE.SKILL.md      # Enterprise patterns
├── skill/
│   ├── skills.md            # Core HTMX expert (rules, activation context)
│   ├── activation.md        # When to activate this skill
│   └── reference/           # Detailed reference docs
│       ├── attributes.md
│       ├── triggers.md
│       ├── swap.md
│       ├── events.md
│       ├── server-patterns.md
│       ├── validation.md
│       ├── security.md
│       ├── performance.md
│       ├── headers.md
│       └── anti-patterns.md
├── examples/                # Express demo, pattern examples
├── tests/                   # Validation tests
└── .github/workflows/       # CI/CD

Testing

Run the test suite:

npm test

This validates:

Skill file format compliance
Example file structure
HTMX pattern correctness

Contributing

Contributions welcome! Please ensure:

Skills follow the format guidelines
Examples demonstrate correct HTMX patterns
Tests pass before submitting PRs

License

MIT License - see LICENSE file

Htmx Claude Skill

Install / Use

README