# Extend kli


kli is a live image. A small boot kernel installs the extension protocol. Everything
above it (the model providers, the tools, the slash commands, the terminal UI) is an
extension installed into that protocol with a retractor. You extend kli by installing
more of the same: there is no privileged built-in path, only contributions and the
two operations that add and remove them.

## One mechanism, three altitudes

The mechanism is constant. A contribution installs against the protocol and carries a
retractor that undoes exactly what it installed. What changes between altitudes is how
much of the contribution you write yourself.

1. **Feed a builtin extension a resource.** The `prompt-templates` and `skills`
   extensions ship in the image. Drop a Markdown file in an extensions directory and
   the builtin's effect registers a slash command for it, with a retractor that
   unregisters it on unload. You write no Lisp; you hand data to the builtin
   `prompt-templates` and `skills` extensions, which someone already wrote.
2. **Write a contribution.** A `defextension` form adds tools, commands, themes, event
   handlers, or methods. Requirements for the common kinds are derived from the clauses
   you write, and each kind retracts. See [Lisp extension anatomy](/kli/extend/lisp-extensions/anatomy)
   and [Contribution kinds](/kli/extend/lisp-extensions/contribution-kinds).
3. **Define a new contribution kind.** The kernel's own vocabulary (`:tool`, `:method`,
   `:effect`, `:theme`) is built with `defcontribution-kind`. When no existing kind
   fits a domain, you add one and `defextension` learns to compile its clause. See
   [Defining a contribution kind](/kli/extend/lisp-extensions/defining-a-contribution-kind).

## Extensions all the way down

The altitudes are not tiers of a ladder; they are the same install/retract shape seen
at three depths. `prompt-templates` and `skills` are not a no-code layer bolted under
the Lisp one. Each is a `defextension` whose `(:provides ...)` is a single `effect`
that registers commands against the `commands/v1` capability and pairs an unregister
retractor:

```lisp
(defextension prompt-templates
  (:requires
   (capability commands :contract commands/v1)
   (capability config :contract config/v1))
  (:provides
   (effect prompt-templates
     #'register-prompt-template-commands
     #'unregister-prompt-template-commands)))
```

cairn, a separate tool, contributes its slash commands with the same shape: a
`cairn-commands` effect that registers them against `commands/v1` with a retractor. The
Markdown-prompt path and the kernel's command
machinery run the same mechanism; one writes the effect for you, the other hands you
the macros to write your own. The protocol does not distinguish them.

For the same idea stated as the design's spine and the three pillars it buys you, see
[Extensions all the way down](/kli/concepts/extensions-all-the-way-down).

## Where to go

- [Lisp extension anatomy](/kli/extend/lisp-extensions/anatomy) — `defextension`, the
  manifest as a value, install as a recorded transaction.
- [Contribution kinds](/kli/extend/lisp-extensions/contribution-kinds) — the clause for
  each kind you are likely to write, and what its retraction undoes.
- [Defining a contribution kind](/kli/extend/lisp-extensions/defining-a-contribution-kind)
  — how the kernel defines its own vocabulary, and how you add to it.
- [Extensions all the way down](/kli/concepts/extensions-all-the-way-down) — the spine
  and the three pillars the mechanism buys you.
- [The live image](/kli/concepts/the-live-image) — why installing and retracting is safe
  while kli runs.