[ANN] Kemal Skills v1.12.0.0 released

Community
,
1

Hello! 0/

I’m pleased to announce the release of kemal-skills v1.12.0.0; a collection of 11 modular, empirically verified development skills (SKILL.md) for building high-performance, secure web applications with Kemal and Crystal.

These skills are designed for seamless on-demand progressive discovery in Antigravity CLI (agy), Gemini CLI, Opencode, and compatible AI coding agents.

What’s Covered

The suite provides tested patterns, security postures, and idioms across 11 domains:

Skill Focus
kemal-core Routing, modular Kemal::Router, HTTP QUERY (RFC 10008), response helpers, and Range DoS mitigation.
kemal-websocket Centralized broadcasting Hub, default same-origin validation, and RFC 6455 §4.1 upgrade checks.
kemal-sse Real-time Server-Sent Events (SSE) streaming, injection protection, and Time::Span retry timeouts.
kemal-middleware Custom middleware with use keyword, handler stacks, and wildcard ("*") method/path filtering.
kemal-upload Multipart uploads, pre-validation, unique storage names, and body size limits.
kemal-json JSON APIs, chainable responses (env.json), symbol statuses (:created), and safe JSON parsing.
kemal-auth Session-based authentication with kemal-session, Bcrypt hashing, and access control helpers.
kemal-oauth OAuth2 workflows (GitHub/Google), CSRF state validation, and token exchange.
kemal-database Raw SQL & SQLite integration with DB::Serializable mappings.
kemal-orm Crecto ORM models, validations, and centwise currency storage.
kemal-view Server-side ECR templates, layout yields (<%= content %>), and local variable bindings.

Empirical, Test-First Methodology

Every instruction, parameter parser, and security configuration is extracted directly from upstream Kemal source code and verified against crystal spec (all 332 specs passing).

We follow a 4-component versioning scheme (v<Major>.<Minor>.<Patch>.<Revision>):

  • v1.12.0.0 tracks the Kemal 1.12.0 framework release, with .0 tracking our skill revision counter.

Quick Start & Installation

Clone and install globally to your agent configurations (~/.gemini/config/skills/ and ~/.config/opencode/skills/):

git clone https://gitlab.com/renich/kemal-skills.git
cd kemal-skills
make install

Once installed, your AI agent will automatically discover and activate relevant skills when you ask it to work on Kemal routes, WebSockets, or database integrations.

Feedback, issues, and contributions are warmly welcome.

NOTE:
The announcement was written by Renich and embellished by Gemini.

2

This looks awesome @renich , we recently merged Add Crystal-Kemal agent skill by onurcangnc · Pull Request #774 · kemalcr/kemal · GitHub . Do you think we can improve upon with yours? Anything to improve would be great

3

Sure thing!

Mine is based in the Kemal by example repo, the docs and the source code.

I have a methodology written.

Be my guest. Use it as you see fit.

4

Congrats on the release, @renich

Nice work. Before announcing further, we stress-tested the suite the hard way: wrote an app per skill’s guidance, compiled with Crystal 1.21 + Kemal 1.12.0 (shard release, not master), ran it, and diffed every claim against both the 1.12.0 release source and current master. Results below: one finding is security-relevant.

The critical one: the suite documents master, but versions itself as 1.12.0.0

  • query “/route” (RFC 10008): undefined method on 1.12.0. HTTP_METHODS in the 1.12.0 release’s dsl.cr is %w[get post put patch delete options]. QUERY only exists on master.
  • Kemal.config.max_ranges (kemal-core): not in 1.12.0. Master-only.
  • WS 405-on-non-GET rejection (kemal-websocket): no such path in 1.12.0. Master-only.
  • WS origin default (this one bites): kemal-websocket says an empty websocket_allowed_origins enforces same-origin + 403 on missing Origin. That’s master behavior. On 1.12.0 the same empty allowlist hits return true if allowed.empty?, so all origins are allowed. We verified live: cross-origin upgrade from a hostile origin returns 101 on 1.12.0. An agent following the skill on the release your version string claims to track will believe it’s protected while it’s wide open.

Suggestion:

Keep the 4-component scheme, but add an explicit compatibility matrix per skill (works-on: 1.12.0 / master-only: query, max_ranges, 405, same-origin default), or cut a v1.12.0.x that only contains release-verified content and moves master APIs behind a clearly marked “unreleased” flag.

Architecture / DRY / patterns (the good and the improvable)

The Template Method discipline (all 11 skills share the same 4-section skeleton), zero cross-skill coupling, and the registry index are genuinely well executed.

To fix:

  1. DRY: env.json / env.status response-helper patterns are repeated in kemal-core, kemal-json and kemal-sse. Pick one canonical home (kemal-json), reference it elsewhere. Same for version labels, scattered across skills (1.9+ / 1.10+ / 1.11+ / 1.12+).
  2. Progressive disclosure / token cost: each skill is a flat 3.6–6 once on activation. For single-domain tasks that’s already leanerthan the in-repo crystal-kemal skill (7.7 KB base). But the full pattern sections (“Patterns from Source Code”) could move to per-skill references/ files ldemand. That’s where the in-repo my skill structure beats it, and it would cr without losing the deep material.
  3. Clean code: reference paths point at src/kemal-by-example/ as if local, but it’s a submodule not initialized by default. A one-line note in index.md would save agents (and humans) a dead-end.

For the PR:

kemalcr/kemal currently shipped a single crystal-kemal skill in .gitonly, uses the now-deprecated add_handler, and has noapplication-layer coverage (auth, OAuth, DB, uploads). Your suite is the superset and empirically better.

Once the version gates land, please open a PR to kemalcr/kemal proposing the kemal-skills suite. I will be happy to review it. If you have a further question or incremental in terms of token usage, performance or any other thing, feel free to reach out directly me through email, LinkedIn or directly GitHub PR.

Sincerely yours,

Onurcan

5

Yep. Thank you for the extensive review. Spent all night coding so I’m going to get some sleep but as soon as I wake up I’ll attend to your observations and prepare the PR.

I am glad that you find this work useful.

My pleasure, Onurcan.

6

Feel free to create your PR I’ll wait :slight_smile: @renich

7

I’ve released v1.12.0.1.

https://gitlab.com/renich/kemal-skills/-/blob/master/CHANGELOG.rst

image
image1326×689 135 KB

I will, now, proceed with the PR request.

8

Heh! PR #777. I got lucky. ;D

9

Looks fine @renich , are you able to open a PR on GitHub. Unfortunately, I do not have a GitLab account to handle it. Moreover, can you make the skills (~/.gemini/config/skills/) global ? (gemini, claude, codex maybe opencode) and so on… ?

10

It has been done. feat(skills): integrate modular domain skills and modernize crystal-kemal by renich · Pull Request #777 · kemalcr/kemal · GitHub @onurcangnc