# Use agent skills

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


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

- elelem and `elelem-builtins` installed, with a working provider. See
  [the Quickstart](/docs/quickstart/).

## 1. Install and load elelem-skills

```bash
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.

```bash
mkdir -p .agents/skills/commit-style
```

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

```markdown
---
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:

```bash
elelem-skills list
```

```text
commit-style: How to write commit messages in this repository. Use before running git commit.
```

## 3. Use it in a session

```bash
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.

```text
> commit the staged changes
```

```text
+ 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:

```text
> /skills
```

```text
- **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.

```text
.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:

```bash
elelem-skills fetch example.com
```

Or from inside a session:

```text
> /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

- [Connect MCP servers](/guides/mcp-servers/) for tools that live in
  other programs.
- [Write a tool plugin](/guides/write-a-tool/) when a skill needs code,
  not instructions.
- Read the [elelem-skills](/plugins/skills/) page.


Canonical: https://elelem.sh/guides/agent-skills/