Choose the right knowledge type so your agent loads only what it needs

• Knowledge Library & Memory
• Context Engineering
• Agent & Tasks

Rules: constrain behavior, always in effect#

Root-rule interoperability#

kxen recognizes these files at your Workspace root:

• file:///path/to/workspace/AGENTS.md
• file:///path/to/workspace/CLAUDE.md
• file:///path/to/workspace/GEMINI.md
• file:///path/to/workspace/.cursorrules

These root rules are always treated as active.

Layered AGENTS.md#

When a task touches specific files, kxen walks from that file's directory up to the Workspace root looking for nearby AGENTS.md files. A rule closer to the target file gets a more specific scope.

For example, file:///path/to/workspace/src/AGENTS.md only applies to tasks touching the src subtree — it never pollutes context for unrelated directories.

Rule entries#

Project Rules can live at file:///path/to/workspace/.agents/rules/. Personal Rules can live at file:///Users/you/.agents/rules/.

Rule frontmatter supports:

• alwaysApply: always active.
• globs: active when a touched file matches the pattern.
• enabled: whether it participates in rendering at all.
• description: shown in the index when it isn't active.

An inactive Rule only shows in the index — its body isn't injected in full. An index.md in the directory can provide a hand-curated map of your rules.

Built-in Coding Rules#

kxen also ships a set of built-in Coding Rules, toggled independently at the top of Knowledge Library. They aren't project Rules — project content can never modify built-in Safety.

Priority#

Safety outranks every Rule. A project Rule can never grant a read-only role write access, and can never turn off a dangerous-operation denial or Approval.

Skills: reusable, on-demand instructions#

A Skill is a discoverable, callable instruction package. Its full body loads only when needed — kxen never stuffs every Skill's content into every request up front.

How it's stored#

Project Skills can use a directory form:

file:///path/to/workspace/.agents/skills/review/SKILL.md

Other files alongside SKILL.md in the same directory are Skill resources — they're never scanned as separate Skills on their own. You can also use a single Markdown file inside the skills directory.

Personal Skills live at file:///Users/you/.agents/skills/.

What a Skill needs#

A Skill must provide a clear description, or it never appears in the discovery and invocation list. You can also configure:

• when_to_use
• arguments
• needs
• user_invocable
• disable-model-invocation

needs injects dependent knowledge alongside the Skill when it loads — it's never a permanent addition to the system prompt.

How it's invoked#

A Skill you can invoke yourself shows up in Composer's / list. A Skill the model is allowed to invoke shows up in the on-demand skill tool.

disable-model-invocation restricts a Skill to your own explicit trigger only. user_invocable controls whether it appears in your own invocation surface at all.

Arguments#

A Skill supports $ARGUMENTS, $1 through $n, and $ARGUMENTS[i]. With no placeholder present, arguments are appended to the end of the loaded body.

Execution boundary#

• A project Skill in an untrusted Workspace never enters the invocable list.
• The same Skill with the same arguments can't be loaded twice in the same Session.
• Skill-calling-Skill recursion is capped at depth 3.
• A Skill can only guide the agent — it can never override role permissions, Safety, or Approval.

Commands: explicit slash triggers#

A Command is an entry point you trigger explicitly. It fits high-frequency actions and task templates that need explicit parameter prompts.

Where you use it#

Type / at the start of a line in Composer to see Commands. Cmd+K opens the command palette, which can also search for and insert a Command.

A Slash Command only triggers at the start of a message — a / in the middle of your text is never expanded into a Command, so an ordinary path or piece of text never gets misread as one.

Built-in Commands#

Currently: /write-goal, /ultracode, /ultraplan, /ultrareview, /doctor, /compact.

These built-ins don't read a template body from the knowledge catalog. /doctor and /compact are recognized and executed directly by the backend; /write-goal and the three /ultra* commands enter a normal agent run, orchestrated by a built-in system-prompt playbook — they still need an available model.

/compact immediately tries to compress the current Session's older model context into a durable summary, without deleting the original Session JSONL. Starting a new Session, switching models, and interrupting a run each use their own dedicated action — "New Session," the Model Picker or Command Palette, and Composer's Stop button — none of them are Slash Commands.

Custom Commands#

A project Command lives at file:///path/to/workspace/.agents/commands/; a personal Command lives at file:///Users/you/.agents/commands/.

Custom Commands support:

• description
• argument-hint
• needs
• $ARGUMENTS and positional arguments

When you send one, kxen expands the template and its dependent knowledge, then hands it to the current Session.

Trust boundary#

A project Command in an untrusted Workspace can appear in the index, but its project-provided body never gets expanded. A Command can never grant the current role a tool it doesn't already have, and can never route around Safety.

Compared to Skills#

A Command is always triggered by you, explicitly, through /. A Skill can be triggered by you, or loaded by the model on demand when allowed.

References: material you read on demand, never auto-injected#

References hold material your agent might need, but shouldn't auto-load on every request. Typical content includes architecture notes, interface contracts, domain vocabulary, and long operating manuals.

Where it lives#

• Project scope: file:///path/to/workspace/.agents/references/
• Personal scope: file:///Users/you/.agents/references/

Markdown files here get scanned as Reference entries. Markdown inside an unrecognized knowledge subdirectory also defaults to being treated as a Reference.

Progressive disclosure#

A Reference's description and location enter the knowledge index; its body is never auto-injected in full the way an active Rule is. The agent judges relevance first, then reads what it actually needs.

This keeps every request from carrying a long document by default, and lets you maintain a knowledge base far larger than any model's context window.

index.md#

Each directory level can use an index.md as a hand-curated entry point. It's a good place to explain:

• What material lives at this level.
• What problem each piece solves.
• A recommended reading order.
• Dependencies between pieces.

An index.md's body enters the rendered result as a knowledge map — it never substitutes for the specific References themselves.

Compared to Rules#

A Rule expresses "must do it this way," and constrains behavior directly once active. A Reference expresses "might need to know this to finish the task," and defaults to on-demand reading. Don't turn long background material into an always-injected Rule.

History: material worth keeping, without injecting it#

History is the historical-entry type in the unified knowledge system. It keeps material still worth consulting, without treating it as a current rule or something to auto-inject as memory.

Where it lives#

• Project scope: file:///path/to/workspace/.agents/history/
• Personal scope: file:///Users/you/.agents/history/

History's description and location enter the knowledge index; its body doesn't auto-inject in full by default — the agent reads specific content only when it needs to.

What belongs here#

• Background on a decision that's already closed.
• A before/after comparison around a migration.
• A stable retrospective on finished work.
• Old interface information you'll still occasionally need to look up.

What doesn't belong here#

• A constraint you must currently follow — that belongs in Rules.
• Authoritative material a current task needs — that belongs in References.
• A repeatable process — that belongs in Skills.
• A stable fact that should auto-retrieve — that belongs in Notes or Memory.
• A one-off research log, analysis output, or verification result isn't long-term product knowledge.

History existing doesn't mean its content is still valid. An entry's description should state its timeframe and expiry boundary clearly, so old information never gets mistaken for current product behavior.