Skip to main content
skill CX Codex

hono · oakoss — Claude Code skill: what it does, how to install

Guides coding agents in building lightweight APIs, middleware pipelines, and RPC servers using the Hono framework.

MIT 112 installs ★ 29 updated 2026-08-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill hono -a claude-code
Open on GitHub

What hono does

This skill supplies the agent with design patterns and conventions for Hono across runtimes like Cloudflare Workers, Bun, Deno, and Node.js. It guides path routing, regex parameter constraints, request validation using @hono/zod-validator, and typed context propagation with c.set() and c.get().

It also details in-memory testing with testClient and end-to-end type safety via the hc RPC client. Exporting RPC types requires route chaining like app.route('/a', a).route('/b', b); exporting the base app type breaks type inference on the client side. The guide also highlights edge behaviors, such as omitting compress() middleware on Cloudflare Workers and Deno Deploy because those environments compress responses automatically.

What it helps with

  • scaffold edge APIs for Cloudflare Workers, Bun, or Node.js
  • set up type-safe client-server communication using Hono RPC
  • validate request bodies and query parameters with Zod
  • run in-memory integration tests using testClient without starting a server

Example prompts for the agent

  • Build a Cloudflare Workers REST API with Hono and Zod request validation
  • Configure an RPC route hierarchy in Hono and set up a typed hc client
  • Write unit tests for the auth router using testClient from hono/testing

How to install hono

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill hono -a claude-code

2Manually: put the files in place

~/.claude/skills/hono/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/hono/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about hono

How do I install hono in Claude Code?

Run npx skills add oakoss/agent-skills --skill hono -a claude-code in your terminal.

What does the hono skill do?

It provides your agent with reference patterns for the Hono web framework, including route grouping, typed middleware, RPC exports, and runtime adapters.

When should Hono not be chosen?

Hono is not built for full-stack SSR monoliths better served by Next.js or Remix, nor for architectures relying on Node.js-only modules lacking Web Standard equivalents.

Source text

SKILL.md · MIT
---
name: hono
description: 'Hono ultrafast web framework for edge and server runtimes. Use when building APIs, middleware chains, or edge functions on Cloudflare Workers, Bun, Node.js, or Deno. Use for hono, api, routing, middleware, cloudflare-workers, edge, rpc, validator, context.'
license: MIT
metadata:
  author: oakoss
  version: '1.1'
  source: 'https://hono.dev/docs/'
user-invocable: false
---

# Hono

## Overview

Hono is a small, ultrafast web framework built on Web Standards that runs on any JavaScript runtime including Cloudflare Workers, Bun, Deno, Node.js, Vercel, and AWS Lambda. Application code is portable across runtimes; only the entry point and adapter differ per platform.

**When to use:** Edge-first APIs, Cloudflare Workers services, multi-runtime applications, lightweight REST/RPC servers, middleware-heavy request pipelines, type-safe client-server communication.

**When NOT to use:** Full-stack SSR frameworks (use Next.js/Remix), heavy ORM-driven monoliths where Express ecosystem maturity matters, applications that need deep Node.js-only APIs without Web Standard equivalents.

## Quick Reference

| Pattern           | API                                         | Key Points                                  |
| ----------------- | ------------------------------------------- | ------------------------------------------- |
| Basic routing     | `app.get('/path', handler)`                 | Supports get, post, put, delete, patch, all |
| Path parameters   | `app.get('/user/:id', handler)`             | Access via `c.req.param('id')`              |
| Regex constraints | `app.get('/post/:id{[0-9]+}', handler)`     | Inline regex in path parameter              |
| Wildcard          | `app.get('/files/*', handler)`              | Matches any sub-path                        |
| Route grouping    | `app.route('/api', subApp)`                 | Mount sub-applications                      |
| Middleware        | `app.use(middleware())`                     | Executes in registration order              |
| Path middleware   | `app.use('/auth/*', jwt(...))`              | Scope middleware to paths                   |
| JSON response     | `c.json({ key: 'value' })`                  | Sets Content-Type automatically             |
| Text response     | `c.text('hello')`                           | Returns plain text                          |
| HTML response     | `c.html('<h1>Hi</h1>')`                     | Returns HTML content                        |
| Status + header   | `c.status(201)`, `c.header('X-Key', 'val')` | Chain before response                       |
| Redirect          | `c.redirect('/new-path', 301)`              | Default status is 302                       |
| Request body      | `c.req.json()`, `c.req.parseBody()`         | JSON or form data parsing                   |
| Query params      | `c.req.query('page')`                       | Single query parameter                      |
| Context variables | `c.set('user', data)` / `c.get('user')`     | Type-safe middleware data passing           |
| Zod validation    | `zValidator('json', schema)`                | `@hono/zod-validator` package               |
| RPC client        | `hc<AppType>(url)`                          | End-to-end type-safe API calls              |
| Error handler     | `app.onError((err, c) => ...)`              | Global error handling                       |
| Not found         | `app.notFound((c) => ...)`                  | Custom 404 handler                          |
| Environment       | `c.env.BINDING_KEY`                         | Access runtime bindings/env vars            |
| Adapter helper    | `env(c)` from `hono/adapter`                | Unified env access across runtimes          |
| WebSocket         | `upgradeWebSocket()` from runtime adapter   | WebSocket helper with RPC support           |
| Test client       | `testClient(app)` from `hono/testing`       | Type-safe testing without HTTP server       |
| JSX streaming     | `jsxRenderer({ stream: true })`             | SSR streaming with Suspense support         |

## Common Mistakes

| Mistake                                                             | Correct Pattern                                                                      |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Registering middleware after handlers                               | Register middleware before the handlers it should apply to                           |
| Using `app.route()` without chaining for RPC types                  | Chain route methods (`app.route('/a', a).route('/b', b)`) and export `typeof routes` |
| Forgetting `export default app` for edge runtimes                   | Cloudflare Workers, Bun, and Deno require the default export                         |
| Using `compress()` on Cloudflare Workers or Deno Deploy             | These platforms compress automatically; skip the middleware                          |
| Mixing Hono and middleware versions in Deno                         | Pin all `hono` imports to the same version to avoid type mismatches                  |
| Wrapping `next()` in try/catch inside middleware                    | Hono catches thrown errors and routes to `app.onError()`; `next()` never throws      |
| Defining routes with `app.get()` but exporting `typeof app` for RPC | Export the type of the chained route variable, not the app instance                  |
| Using `new Hono()` without generics for typed context               | Pass `Hono<{ Variables: MyVars }>` to enable typed `c.get()`/`c.set()`               |
| Returning `c.json()` without status for created resources           | Pass status as second argument: `c.json(data, 201)`                                  |
| Not using `createMiddleware()` for reusable middleware              | Import from `hono/factory` to preserve type inference when extracting middleware     |

## Delegation

> If the `zod` or `typescript-patterns` skill is available, delegate schema and type-level tasks to it.
> Otherwise, recommend: `npx skills add oakoss/agent-skills --skill typescript-patterns`
>
> If a Cloudflare Workers skill is available, delegate platform-specific configuration to it.

## References

- [Route definitions, path params, groups, and method handlers](references/routing.md)
- [Built-in and custom middleware patterns](references/middleware.md)
- [Context object, request parsing, and response helpers](references/context-and-helpers.md)
- [Zod validator middleware and request validation](references/validation.md)
- [RPC client and end-to-end type safety](references/rpc-client.md)
- [Runtime adapters for Cloudflare, Bun, Node.js, Deno, and more](references/adapters.md)
- [Testing with testClient, WebSocket helper, and JSX streaming](references/testing-and-websocket.md)

© oakoss · MIT · oakoss/agent-skills

Similar skills

All skills for Backend and APIs →

hono by other authors comes first.

hono honojs Feeds the agent Hono API knowledge and makes it verify apps through Hono CLI instead of throwaway scripts. CX Codex +1 4,500installs hono suhaibjanjua This skill guides Hono API and app development, covering routes, middleware, validation, and typed RPC clients. Use it when building for runtimes such as Bun or Cloudflare Workers. CX Codex +1 54installs hono-api-scaffolder jezweb hono-api-scaffolder scaffolds Hono API routes for Cloudflare Workers with Zod validation, error handling and API docs. Use it after the project shell is in place. CX Codex +1 1,600installs hono-typescript Mindrally hono-typescript is a Claude Code skill for Hono and TypeScript APIs on Cloudflare Workers, Deno, Bun, and Node.js. It activates for routes, middleware, validation, and error handling. CX Codex +1 872installs bun-hono-integration secondsky bun-hono-integration — a skill that tells the agent how to build Hono APIs on Bun: routes, middleware, Zod validation, RPC client. Useful when your project already runs on Bun. CX Codex +1 473installs hono-routing secondsky hono-routing — a skill for building Hono APIs: routes, middleware, Zod or Valibot validation, RPC client with type inference. Covers 12 common errors and their solutions. CX Codex +1 256installs hono-rpc bobmatnyc Walks through Hono RPC: export AppType on the server, call hc<AppType> on the client, skip codegen entirely. CX Codex +1 460installs hono-core bobmatnyc hono-core — a skill for Claude Code, Codex, Cursor, and other platforms that gives the agent a working knowledge of Hono — routing patterns, the context object, and response methods. CX Codex +1 509installs

From the same set106

The whole set →
better-auth Hands the agent a reference for better-auth: config, plugins, session strategies and the usual mistakes. Useful when a project needs login, 2FA or multi-tenant organizations. CX Codex +1 114installs meta-skill-creator The meta-skill-creator skill guides you through building and validating agent skills that follow the Agent Skills open standard. Use it to plan a SKILL.md and organize supporting files. CX Codex +1 114installs figma-developer figma-developer pulls colours, type styles and icons out of Figma over the REST API and turns them into CSS variables and React components. Useful when the design file moves faster than your code. CX Codex +1 114installs tanstack-store A reference skill that teaches the agent how TanStack Store works: stores, derived values, batching, effects. Useful when state is shared across components. CX Codex +1 113installs astro Feeds the agent Astro patterns: content collections, island hydration, view transitions, rendering modes. Useful when most pages are static with a few interactive parts. CX Codex +1 111installs db-enforcer db-enforcer is a Claude Code skill that checks PostgreSQL integrity and alignment with Prisma. It activates for schema design, migration work, and RLS policy setup. CX Codex +1 109installs electricsql Briefs your coding agent on ElectricSQL: streaming slices of Postgres to the client through Shapes, plus the proxy and write patterns around it. CX Codex +1 109installs trpc trpc is a Claude Code skill for building type-safe TypeScript APIs with tRPC v11. It comes into play when working on routers, procedures, React clients, or tests. CX Codex +1 109installs

Project sponsors

Companies that keep this analytics open