elelem-skills

A skill is a Markdown file of instructions for one kind of task, in the agent skills format. elelem-skills finds them on disk and tells the model which ones exist. The model loads a skill’s full text only when it needs it, so 20 skills cost 20 short summaries in the prompt, not 20 documents.

Install #

gem install elelem-skills

elelem loads plugins from ~/.agents/plugins/*.rb and .agents/plugins/*.rb. Add a plugin file that requires the gem:

# ~/.agents/plugins/skills.rb
require "elelem/skills"

The gem also installs the elelem-skills command, which works without this step.

Configure #

Each skill is a directory containing a SKILL.md:

---
name: tdd
description: Test-driven development. Use when the user wants tests written first.
---

# TDD

Red, green, refactor.

The file must start with a --- line. The YAML front matter must have name and description; other keys are ignored. A file without them is skipped with a warning. The body is everything after the closing ---. The skill’s name comes from name, not from the directory.

Skills are discovered in 3 places, one directory level deep:

They are read in that order. When 2 skills share a name, the later one wins: a project skill replaces a personal one, which replaces a fetched one.

Use #

In a session, the model sees a tool named skill. Its description lists every skill as name: description, each cut to 400 characters. Calling it with a name returns the skill’s name, its directory, and its body. The directory lets the model read any other files you keep next to SKILL.md.

You can browse skills yourself with /skills:

/skills                     list skills with their descriptions
/skills tdd                 print the body of the tdd skill
/skills fetch example.com   install skills published by example.com

From the shell:

elelem-skills list
elelem-skills fetch example.com
elelem-skills help

list prints each skill as name: description. fetch prints the names it installed.

Fetch skills from a website #

fetch ORIGIN downloads https://ORIGIN/.well-known/agent-skills/index.json. An origin without a scheme gets https://.

{
  "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json",
  "skills": [
    {
      "name": "tdd",
      "type": "skill-md",
      "url": "tdd/SKILL.md",
      "digest": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
    }
  ]
}

The index must declare exactly that $schema, or the fetch stops. For each entry of type skill-md, elelem resolves url against the index URL, downloads the file, and checks its SHA-256 against digest. On a match it writes the file to ~/.agents/remote-skills/HOST/NAME/SKILL.md. On a mismatch it stops with an error. Entries of any other type, such as archives, are skipped with a warning.

Each install is recorded in ~/.agents/remote-skills/.skill-lock.json:

{
  "version": 1,
  "skills": {
    "example.com/tdd": {
      "host": "example.com",
      "name": "tdd",
      "url": "https://example.com/.well-known/agent-skills/tdd/SKILL.md",
      "digest": "sha256:9f86d0...",
      "installedAt": "2026-11-01T12:00:00Z",
      "updatedAt": "2026-11-01T12:00:00Z"
    }
  }
}

Fetching the same origin again overwrites the files and updates updatedAt.

How it works #

The plugin’s setup block builds a catalog of skills when the session starts, registers the skill tool with the catalog in its description, and registers /skills. Skill bodies stay on disk until the tool or the command asks for one.

After /skills fetch, the catalog is rebuilt, so new skills work with /skills and the skill tool right away. The tool’s description, which is what the model reads, is not rebuilt until you restart elelem.

Limitations #

• The digest comes from the same server as the skill. It catches corruption, not a compromised server. With an http:// origin there is no transport security either.
• HTTP redirects are not followed; any non-2xx response is an error.
• A digest mismatch stops the fetch, but skills earlier in the index stay installed.
• The lockfile is a record. Nothing reads it back to verify or update skills.
• There is no command to remove a skill. Delete its directory.
• Only skill-md entries are supported. Archive skills are not.
• SKILL.md must use \n line endings; a file starting with ---\r\n has no front matter as far as elelem is concerned.
• Every skill’s summary is part of the skill tool description, so it is sent with every request.

Development #

git clone https://git.mokhan.ca/elelem/skills.git
cd skills
bin/setup
bin/test