Hooks and skills
Two ways to shape a run without touching the agent: hooks fire on lifecycle events, skills load instructions when they become relevant.
Hooks
A hook is a command that runs at a point in the agent's lifecycle — before a tool call, after a file is written, when a session ends. The agent does not decide whether to run one; the runtime does, which is what makes hooks the right place for a rule that must hold every time rather than usually.
That is the whole distinction worth internalising: an instruction in your project memory is advice the model can weigh against everything else in context. A hook is enforcement. "Format after every edit" is a hook. "Prefer tabs" is memory.
Hooks receive context through KAEONIX_* environment variables — which event fired, which tool, which path. A hook that exits non-zero on a PreToolUse event blocks the call, so the same mechanism does both automation and policy.
Skills
A skill is a folder of instructions the agent loads when it becomes relevant, rather than carrying in every request. Each declares a description; the agent matches against it and pulls the body in only when the work calls for it.
This exists because context is the scarce resource. Twenty pages of deployment procedure prepended to every turn is twenty pages of tax on questions that have nothing to do with deploying. As a skill, it costs nothing until someone deploys.
Skills resolve from ~/.kaeonix/skills/ and ./.kaeonix/skills/, so a project can ship its own alongside your personal set.
Which one to reach for
- It must happen every time — a hook. Formatting, linting, a commit convention, a forbidden command.
- It is knowledge the agent needs sometimes — a skill. A runbook, a domain model, a house pattern.
- It applies to everything you ever do here — project memory, kept short.