The system has four layers. Each one answers a different question for the agent.
A small set of always-loaded files plus a lookup order (see ../AGENTS.md).
The design constraint is subtraction, not addition. The instinct is to tell the agent everything. That backfires: long context is expensive and it pushes the model toward whatever you over-described. So the context layer holds three things only:
- Corrections the model cannot infer (conventions, past mistakes, preferences).
- A lookup order so the agent fetches deep context on demand instead of up front.
- Pointers (HUB files, an index) rather than the content itself.
Durable facts live in a memory/ folder, one fact per file, with a one-line index
the agent reads each session. New facts get appended; wrong facts get deleted.
A skill is one workflow with one job, written so the agent can invoke it by name.
Each skill is a folder with a SKILL.md (instructions + when to use) and optional
scripts. See ../skills/ for the authoring guide and a worked example.
Good skills share three traits: a sharp trigger (when to use, and when not to), a deterministic core (so results are repeatable), and explicit anti-patterns (the mistakes the agent should avoid). A skill that tries to do everything is worse than no skill.
Hooks are deterministic scripts the harness runs around tool calls. They are not the model. That distinction matters: a preference in a context file is a suggestion the model may ignore; a hook is code that always runs.
Typical uses: rewrite a command to a cheaper equivalent, redirect a file read
through a converter, inject a one-line nudge when a prompt matches a known pattern,
tidy outputs on a schedule. See ../hooks/.
CLIs and MCP servers. The rule is CLI first: a direct CLI or API is more reliable, uses fewer tokens, and does not drop a connection mid-task. MCP servers fill the gaps where no good CLI exists.
prompt
│
├─ hook may inject a nudge or rewrite a command
│
▼
agent reads context layer (lookup order, not everything)
│
├─ matches a skill? ──▶ run the skill (deterministic core)
│
▼
calls tools (CLI first, MCP fallback)
│
├─ hook may post-process the result
│
▼
answer, then write back to the HUB / memory if state changed
The bottleneck in agent work is rarely the model. It is context hygiene (giving the agent the right slice, not all of it) and repeatability (so the same task does not get solved a different way each time). The four layers exist to make those two things cheap.