EONYX skills: how Agent Skills and SKILL.md work

A skill is a folder with a SKILL.md file: an instruction the agent loads when a task matches it. Skills let you package repetitive procedures — a code review, a deploy checklist, the rules for formatting a report — so that they don’t take up context until they’re needed.

1 How a skill works

A skill is a folder with an instruction; let’s look at how the model loads it, what SKILL.md consists of, and what finished skills look like.

1.1 Progressive disclosure

The key idea: only the name and description of each skill make it into the system prompt — a short catalog under the ## Available Skills heading. The model receives the full text of a skill only when it calls the load_skill tool itself:

## Available Skills
- **review**: Check the diff for bugs and style before committing
- **deploy**: Production rollout checklist

→ the model decides the task is about a review
→ calls load_skill {"name": "review"}
→ receives the full text of SKILL.md

That way a dozen skills cost a couple hundred tokens of context instead of tens of thousands. The model makes the “when to load” decision — which is why the quality of the description field decides everything.

1.2 The structure of a skill

A skill is a subdirectory with a SKILL.md file:

skills/
└── review/
    └── SKILL.md

SKILL.md starts with frontmatter between ---, followed by the body of the skill:

---
name: review
description: Check the diff for bugs, style, and tests before committing. Use it for phrases like "review", "check my changes", "before I commit".
tags: [git, quality]
---

# Reviewing changes

1. Look at the diff: `git_diff`, with staged=true if needed.
2. Go through every changed file: logic, mistakes, stray edits.
3. Verify that the tests were run: `go test ./...`.
4. Structure the answer like this: critical → nice to have → nitpicks.

Frontmatter fields:

Frontmatter is written in YAML (key: value); a JSON object is accepted as well. If description is not set, the catalog gets a No description provided placeholder — the model is unlikely to figure out that it should load such a skill.

1.3 Skill examples

---
name: deploy
description: Production rollout checklist. Use it when asked to deploy, roll out, or prepare a release.
tags: [ops]
---

# Deploy

1. `git_status` — the working tree is clean, the branch is main.
2. `go test ./...` and `go vet ./...` — green.
3. Build the tag: the version from `git describe --tags` + an increment.
4. NEVER push a tag without confirmation from the user.

---
name: commits
description: The rules for writing commit messages in this project. Use it before any git_commit.
tags: [git]
---

# Commits

- Subject: imperative mood, English, up to 60 characters.
- No mentions of tools or bots.
- A body only if the "why" isn't obvious from the subject.

2 Discovery and management

What’s left is understanding where EONYX takes skills from and how to turn them on right inside a session.

2.1 Search directories

Directories are scanned in priority order — on a name collision the first one found wins:

So a project-level review overrides your global review. In addition:

• The EONYX_SKILLS_DIR variable (a list of paths separated by the OS separator) replaces the entire list of directories.
• The skills array in eonyx.json appends directories after the standard ones:

"skills": ["/opt/team-skills", "../shared-skills"]

What was found is visible in eonyx config (the Skills section) and in the TUI header: the # skills segment lists the active skills.

2.2 Managing skills in a session

Ctrl+K opens the capabilities dialog, the Skills tab: any skill can be turned off or on on the fly (✓/✗). Toggling immediately rebuilds the catalog in the system prompt and rebinds load_skill to the active set — the model no longer sees a disabled skill and cannot load it.

load_skill is a read-only tool by its nature, but formally it isn’t in the always-allowed list; in the TUI its call goes through the regular permission dialog, or you can add it to allowed_tools.

3 Summary