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
npx skills add oakoss/agent-skills --skill hono -a claude-codeWhat 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
testClientwithout 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
hcclient - Write unit tests for the auth router using
testClientfromhono/testing
How to install hono
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill hono -a claude-code2Manually: put the files in place
~/.claude/skills/hono/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/hono/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill hono -a codex2Manually: put the files in place
.agents/skills/hono/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill hono -a cursor2Manually: put the files in place
.cursor/skills/hono/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install oakoss/agent-skills skills/hono2Manually: put the files in place
.github/skills/hono/SKILL.md1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill hono -a gemini-cli2Platform CLI
gemini skills install https://github.com/oakoss/agent-skills --path skills/honoManually: put the files in place
.devin/skills/hono/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill hono -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.