AI Skills

Heximon ships an Agent Skill — a self-contained reference that teaches AI coding assistants how to build Heximon apps correctly, so they don't reach for a decorator.

Why a skill at all

Heximon doesn't look like most TypeScript backends an LLM has seen. There are no decorators, no injection tokens, and no runtime DI container. A class becomes part of the app by being listed in a module's config and recognized by the concept base it extends or implements; its constructor parameters are its dependencies.

An assistant answering from generic priors will confidently reach for decorator syntax — annotations Heximon rejects at compile time.

The skill closes that gap: it encodes the invariants, the package map, and the authoring idioms so a skill-aware agent generates Heximon-correct code from the first try instead of decorator-shaped guesses.

Without the skill, an unprimed agent reaches for the decorator API it's seen a thousand times — and Heximon rejects it at build time:

// what an unprimed agent writes — rejected at build: no decorators at all
@Controller("/users")
export class UsersController {
  @Get("/:id")
  findOne() {}
}

With the skill installed, the same request produces the implements form the compiler actually reads — this is the real controller from examples/ladder/L01-minimal/src/users/users.controller.ts:

import type { Controller, Get } from "@heximon/http";
import { type User, UsersRepository } from "./users.repository";

export class UsersController implements Controller<"/users"> {
  constructor(private readonly users: UsersRepository) {}

  public async list(_action: Get<"/", { scopes: ["public"] }>): Promise<User[]> {
    return this.users.list();
  }

  public async get(action: Get<"/:id">): Promise<User | { error: string }> {
    const user = await this.users.findById(action.request.pathParams.id);
    return user ?? { error: "User not found" };
  }
}

Where it lives

The skill is a folder in the monorepo, docs/skills/heximon/:

• SKILL.md — one document covering the whole authoring surface: the invariants (no decorators, no runtime container, class identity as the only DI token, constructor signatures as the dependency declaration), the package map, and worked idioms for modules, controllers, contracts, CQRS, DDD, Drizzle, auth, and testing.
• references/ — deeper, source-grounded per-area files the skill links out to (events/CQRS, DDD, sagas, workflows, auth, drizzle, observability, testing, and more) for the detail that doesn't belong in the top-level document.

Point a skill-aware tool — Claude Code, or anything that reads local SKILL.md files — at that folder and it picks up both the rules and the deeper references.

What's in SKILL.md

• The invariants — no decorators, no runtime DI container, class identity as the only token, constructor signatures as the dependency declaration, oxc-based compilation into .heximon/.
• The package map — every @heximon/* package and what it provides, so the agent imports the right name from the right place instead of guessing a module path.
• Authoring idioms — modules and DI, HTTP controllers and contracts, middleware and error filters, events/commands/queries, DDD entities and repositories, the Drizzle dialect, auth, and the test affordances — each a worked example, not a one-line blurb.

llms.txt and MCP

This documentation site is built with Docus, which can serve two machine-readable surfaces from the same content, no extra authoring required:

• /llms.txt — a plain-text index of the site's content, generated from the same pages you're reading, for any tool that consumes the llms.txt convention. Enabled for this site.
• /mcp — a Model Context Protocol server exposing this site's content as MCP resources, for an agent that talks MCP instead of fetching pages directly. Docus ships this capability, but it is turned off for this deployment (mcp: { enabled: false } in docs/nuxt.config.ts); enable it in a Docus site's config to serve it.

Both ride the published docs site itself; neither depends on installing the docs/skills/heximon skill separately. Use the skill when you want an agent to author Heximon code correctly; use /llms.txt (or /mcp, once enabled) when you want an agent to look up something from these docs.

Next steps

• Point your project's CLAUDE.md (or equivalent) at docs/skills/heximon/SKILL.md so your agent consults it before writing @heximon/* code.
• Quick Start — build a module and controller by hand to recognize the correct, skill-driven output when you see it.