hanakai-yaku
A library of 35 atomic skills and 10 orchestrated agents that turn any AI coding assistant into a disciplined Hanami collaborator—one that follows conventions, writes tests first, and never guesses.
Scroll to learn how it works
The Problem
Ask an AI to build a CRUD endpoint and you’ll get Rails patterns in Hanami syntax. Controllers where actions belong. Raw SQL where changesets should go. Tests that pass without actually testing. The conventions of Hanami, dry-rb, and ROM are invisible to a generalist assistant.
Without Skills
✖ Raw relation.insert instead of changesets
✖ Business logic in actions
✖ No validation contracts
✖ Container accessed directly, not injected
✖ Tests written after code, or skipped
✖ Rails-isms in Hanami files
With hanakai-yaku Skills
✔ Changesets for every write operation
✔ Thin actions that delegate to operations
✔ Validation contracts with typed schemas
✔ DI via include Deps[...]
✔ Tests written first, red-green-refactor
✔ Native Hanami patterns throughout
The Mental Model
Think of skills as the atomic instructions—each one teaches the AI how to do exactly one thing: create a changeset, define a route, write a migration. Think of agents as pre-wired workflows that chain skills together into complete tasks: build a CRUD resource, setup a slice, implement authentication.
Skills are atomic. Agents chain them. Both enforce the same non-negotiable rule: tests gate implementation.
The Core Rule
Every code-producing skill contains a HARD-GATE—a non-negotiable rule that prevents the AI from writing implementation code until a failing test exists. This is the single rule that makes the library work.
The gate is real
Every skill with a HARD-GATE section instructs the AI: “Write test → Run test → Verify it FAILS for the right reason → Implement → Verify it PASSES.” If the test doesn’t fail first, the AI stops and asks you to fix it. No code gets written without a gate to pass.
How It Works
Open any SKILL.md and you’ll find these sections. Each one serves a specific purpose in guiding the AI through a disciplined workflow.
YAML Frontmatter
Name, description, trigger words, ecosystem sources. Tells the AI when to use this skill.
Quick Reference
Scenario-to-approach mapping. Lets the AI scan and find the right step without reading everything.
HARD-GATE
Non-negotiable TDD rule. Implementation code is blocked until a failing test exists.
Core Process
Step-by-step instructions with code examples, file paths, and expected output.
Integration Table
Names the next skill to load. Skills chain together like function calls.
A Concrete Example
The build-crud-resource agent chains 8 skills into a single workflow. You ask for a CRUD resource, and the AI follows each step in order—never skipping the test gate, never mixing up the layers.
Each arrow is a handoff. When the current skill completes, the Integration table tells the AI which skill to load next. The agent defines the pipeline; the skills execute the steps. At every step, the TDD gate blocks forward progress until tests pass.
The Catalog
Actions (4)
build-json-api, create-action, handle-errors, validate-params
CLI (4)
create-app, generate-components, manage-database, run-development
Context (1)
load-context — discover the app’s slices, providers, settings, and routes
Cross-cutting (2)
manage-settings, review-code
Persistence (5)
create-changeset, create-repository, define-entity, define-relation, write-migration
DI (2)
inject-dependencies, register-provider
dry-monads (1)
handle-result-pattern
dry-rb (2)
create-operation, create-validation-contract
Providers (2)
configure-providers, implement-di
Security (1)
review-security
Routing (1)
define-routes
Slices (5)
configure-slice, create-slice, extract-slice, review-slice-boundaries, test-slice
Testing (3)
write-action-spec, write-request-spec, write-rom-spec
Views (2)
create-view, decorate-with-parts
add-background-jobs
Adapter → inject → enqueue → test
add-table-column
Migration → data layer → test
build-api-slice
Slice → actions → routes → test
build-crud-resource
Entity → migration → repo → actions → views → test
create-new-slice
Generate → routes → DI → test
hanami-setup
Context → providers → DI → verify
setup-authentication
DI → provider → actions → error handling
slice-lifecycle
Create → test → review → extract
tdd-loop
Plan → test → implement → review
validation-contract
Contract → DI → inject → results → test
A Shared Language
The load-context skill discovers your app’s structure—slices, providers, routes, settings—and builds a map the AI uses for every subsequent task. Meanwhile, CONTEXT.md defines 10 core terms so every skill speaks the same language.
Terms every skill uses
Action — HTTP endpoint, thin, delegates to operations
Operation — Business workflow, returns Success/Failure
Repository — Read-only DB interface, never mutates
Changeset — Write rules, every mutation uses one
Slice — Self-contained module, no cross-slice internals
Rules every skill enforces
DI — include Deps[...], never call container directly
Settings — All env values through config/settings.rb
Providers — Every external service gets one
Views — Presentation only, explicit exposures
Relations — Raw data gateways, wrapped by repos
Next Steps
Load your app’s context
Activate @load-context to discover slices, providers, routes, and settings. The AI builds a map it uses for the rest of the session.
Choose an agent for your task
Need CRUD? @build-crud-resource. New slice? @create-new-slice. Auth? @setup-authentication. Each agent chains the right skills in the right order.
Or invoke a single skill directly
Need just one thing? @create-changeset, @define-routes, @write-migration. Every skill is independently invocable.
Follow the Integration table
When a skill finishes, it tells the AI what to load next. Skills chain like function calls. You never need to guess what comes after.
Works in your tool of choice
Claude, Cursor, GitHub Copilot, Google Gemini, OpenCode, and Windsurf all support skill-based AI workflows. Install the pack for your editor and start invoking @skill-name commands today.