Guides

Use agent skills

Write a SKILL.md file, let the model load it when it needs it, and install skills from a remote index.

Beginner 10 minutes elelem-skillselelem-builtins

At the end of this guide elelem will know a skill you wrote: a Markdown file of instructions the model loads only when the task calls for it. You will also know how to install skills published by someone else.

A skill differs from AGENTS.md in when it is read. AGENTS.md goes into every system prompt. A skill costs one line in the skill tool’s description until the model asks for the rest.

Before you start #

1. Install and load elelem-skills #

gem install elelem-skills
mkdir -p ~/.agents/plugins
echo 'require "elelem/skills"' > ~/.agents/plugins/skills.rb

elelem does not load integration gems on its own; the one-line plugin file does it for every session.

2. Write a skill #

A skill is a directory with a SKILL.md file in it. elelem looks in ~/.agents/skills/ for skills you want everywhere and in .agents/skills/ in the current directory for one project.

mkdir -p .agents/skills/commit-style

Create .agents/skills/commit-style/SKILL.md:

---
name: commit-style
description: How to write commit messages in this repository. Use before running git commit.
---
Subject line under 50 characters, imperative mood.
Wrap the body at 72 characters.
Explain why the change was made, not what changed.

The front matter needs both name and description; a file missing either is skipped. The description is what the model reads when deciding whether to load the skill, so say when to use it. Everything after the front matter is the body.

Check that elelem found it:

elelem-skills list
commit-style: How to write commit messages in this repository. Use before running git commit.

3. Use it in a session #

elelem chat -p ollama

elelem-skills adds a tool and a command. The skill tool takes a skill name and returns its body and directory. Its description lists every skill as name: description, so the model knows what exists without reading the bodies.

> commit the staged changes
+ skill({"name" => "commit-style"})

Whether the model loads a skill is up to the model. A clear description that says when to use it is what makes that happen.

The /skills command is for you:

> /skills
- **commit-style**: How to write commit messages in this repository. Use before running git commit.

/skills commit-style prints the body.

4. Bundle files with a skill #

The skill tool returns the skill’s directory along with its body. Put scripts, templates, or reference files next to SKILL.md and refer to them by relative path in the body. The model can read them or run them with the other tools.

.agents/skills/release/
├── SKILL.md
└── checklist.md

5. Install skills from a remote index #

A site can publish skills at /.well-known/agent-skills/index.json. elelem-skills fetch downloads them:

elelem-skills fetch example.com

Or from inside a session:

> /skills fetch example.com

elelem fetches https://example.com/.well-known/agent-skills/index.json, checks that its $schema is https://schemas.agentskills.io/discovery/0.2.0/schema.json, and downloads each entry of type skill-md. Each download is checked against the sha256 digest in the index; a mismatch stops the fetch. Entries of other types, such as archives, are skipped.

Fetched skills go to ~/.agents/remote-skills/HOST/NAME/SKILL.md, and ~/.agents/remote-skills/.skill-lock.json records where each came from, its digest, and when it was installed.

After /skills fetch, the new skills show up in /skills and the skill tool can load them, but the tool’s description still lists the old set. Restart elelem so the model sees them.

Which skill wins #

When two skills have the same name, the last one found wins. The order is remote skills, then ~/.agents/skills/, then .agents/skills/. A project skill overrides a personal one of the same name, and both override a fetched one.

What you built #

A project skill the model loads on demand, a way to check what elelem sees with elelem-skills list and /skills, and a verified way to install published skills.

Next steps #