Skills

You ask kli to cut a release. Without being told which file to look at, it reads your release checklist, follows the steps in order, and stops where the checklist says to stop. You wrote that checklist once as a SKILL.md. kli found it, decided your request matched it, and loaded it. You never typed a command.

That is what a skill buys you over a prompt template. A skill is a SKILL.md file the model can load by itself when the task at hand matches the skill's stated purpose. You install the procedure once; the model reaches for it when it is relevant, with no command from you.

This is still the zero-code altitude of extending kli, and like prompt templates it is itself an extension: the builtin skills extension scans your skills directories and registers each one as a command, retracting them on reload. Like a prompt template, a skill is plain Markdown with no code. The difference is who decides to use it.

How the model finds a skill

At the start of a session kli scans for skills and advertises each one to the model: its name, its description, and where the file is. The description is the whole pitch. When the model judges that the task in front of it matches a description, it reads the file and follows the body. So the description is not a caption — it is the trigger. Write it to say plainly what the skill is for and when it applies, because that sentence is what the model matches against.

The body stays on disk until it is needed. kli advertises the short description always, and the model pulls in the full instructions only when a task calls for them. A session that never touches the skill never reads its body, so the length of the procedure does not weigh on the rest of your work.

A skill is a folder

The unit is a directory whose name is the skill name and that holds a SKILL.md:

release-checklist/
  SKILL.md
  template.md
  scripts/verify.sh

The SKILL.md body can point the model at the other files in the folder. When it loads the skill, kli tells the model where the folder is and that references resolve against it, so the body can say "run scripts/verify.sh" or "fill in template.md" and the model knows where those live. A skill is therefore a small bundle: the procedure plus whatever the procedure needs to hand to the model.

A single SKILL.md with no companion files is also a skill. The folder is the general shape; the lone file is the simple case of it.

What goes in SKILL.md

The file opens with a YAML frontmatter block, and two keys carry the weight. A name gives the skill its identity and its command; leave it out and kli uses the folder name, which is the usual practice. A description is the text the model matches against, so write it to say concretely what the skill does and the situation it fits.

The description is the one key a skill cannot omit. A skill with no description is dropped from the session, because the model would have nothing to match it on. Everything after the frontmatter is the body the model reads once it loads the skill: the procedure itself, in whatever Markdown you like. The exact limits on each field live in the reference.

When a skill beats a prompt template

The two split on one question: who decides to invoke the instructions.

A prompt template fires when you type its slash command. You are in control, and you reach for it deliberately. That fits a prompt you re-send on purpose — a code review you kick off, a commit message you ask for.

A skill fires when the model recognizes the task, whether or not you mention it. That fits a procedure that should apply whenever its situation comes up, even when you did not think to name it: the house style for migrations, the steps for filing a bug, the way this repo wants its changelog written. You encode the knowledge once and let the model apply it in context.

Two more facts follow from this. A skill carries a folder of supporting files, where a prompt template is a single Markdown file submitted as your message. And a skill can hold a much longer body without weighing on every session, because the model loads it only when it is relevant — a template's body is sent in full every time you run it.

If you want a procedure you trigger on demand, write a prompt template. If you want a procedure the model should apply on its own when the moment arrives, write a skill.

You can still invoke a skill yourself

A skill the model can reach is also a command you can reach. Each discovered skill registers as /skill:<name>, so you can load release-checklist yourself with /skill:release-checklist when you want it now rather than waiting for the model to match it. You can also drop $release-checklist into a message and kli expands that skill's body inline before sending. The skill is the same either way; these are extra doors into it.

Where skills live

kli discovers skills from several roots and merges them, with project skills taking precedence over global ones, and a name seen twice keeping the first copy. User-facing roots include <repo>/.kli/skills/ for skills that belong to one project and ~/.config/kli/skills/ for skills you want in every session. kli ships a small set of built-in skills as well, and any skill of yours that shares a name shadows the built-in one. The full discovery order and the rules for what is skipped live in the reference.

To write one now, follow Write a skill.