Skills, but Just the Markdown

#ai#local-models#agents#skills#kodr

“Skills” are having a moment - bundles of instructions you can drop in front of a model to teach it a task. The grand version comes with executable hooks, Python runtimes, install steps, the works. Phase 07 of kodr takes the small version: a skill is a Markdown file, and that is it.

What a skill is here

A SKILL.md file. Kodr discovers them deterministically using the same workspace file listing the context packer already does (see phase 06). Optional YAML frontmatter gives a name and description; if it is missing, the containing directory name is the skill name.

From there, two surfaces:

  • --show-skills prints the skill index - name, description, path - without calling the model. Same instinct as --show-context: let me see what is on offer before anything is sent.
  • --skill NAME_OR_PATH loads only the requested skill bodies into the system prompt. You opt in. Discovery builds an index; loading pulls in the actual instructions.

So the model gets a menu in its system prompt, and the full text of whatever I explicitly asked for. Nothing more.

Why Markdown only

This is the bit I want to be loud about, because it was a deliberate “no”.

An executable skill runtime sounds great until you remember what it drags in: installation, environment setup, a security model, and a trust boundary that suddenly includes arbitrary code from arbitrary skill folders. That is a lot of surface to bolt on at phase 07, especially in a local-first harness where the whole exercise is about being careful with what you hand the model.

Markdown skills give you most of the value - reusable, composable instructions - while staying fully inspectable. A skill is text. You can read it, diff it, and reason about it before it influences a single token. The executable story can come later, once the workflow and tool phases actually need it. Keep the trust boundary small until something forces it open.

It is the same theme running through the whole project: every input the model sees should be something I can look at first.

Links: