Skills

Teach Empryo's agent a framework, workflow or style guide with a SKILL.md file. Browse skills.sh, install per project or everywhere, toggle per session.

Tools3 minutes to read

Copy & share

On this page8 sections

A skill is a folder with a SKILL.md file that teaches the agent something: a framework, a workflow, a style guide or a domain. When a skill is active, its instructions are added to what the agent reads, so it follows them without you repeating them in every prompt.

Empryo finds the skills on your machine when it starts. You choose which ones are active in each session.

Browse and installLink to this section

Press Ctrl+S or run /skills to open the skills manager. It searches skills.sh, a public catalog of community skills.

/skills        open the manager
Ctrl+S         same (terminal UI)

The manager has three tabs:

Search: search the skills.sh catalog, sorted by how often each skill is installed.
Installed: every skill Empryo found on your machine.
Active: the skills turned on in the current session.

ScopesLink to this section

Empryo looks for skills in six folders. Three are global (for every project) and three belong to the current project:

~/.empryo/skills/        global
~/.agents/skills/           global (shared with other tools)
~/.claude/skills/           global (Claude Code compatible)
.empryo/skills/          project
.agents/skills/             project
.claude/skills/             project

If the same skill exists in a global folder and a project folder, the project copy wins. Symlinks are followed, so if one skills folder links to another (for example ~/.agents/skills linked from ~/.claude/skills), each skill is only listed once.

InstallLink to this section

In the manager, select a skill and press Enter. Empryo installs it with bunx, or npx if Bun is not available. The skill lands in the scope you chose and shows up in the Installed tab.

You can also use the skills command line tool yourself:

bash

# Browse popular skills
bunx skills list

# Add from a catalog
bunx skills add <source> --skill <id> -g

Enable and disableLink to this section

Skills are turned on per session. In the Active tab, turn a skill on and the agent starts following it. Turn it off and it is removed from the agent's context. Your choice is saved with the session.

StructureLink to this section

A skill is a folder with SKILL.md at its root:

my-skill/
├── SKILL.md           required, the frontmatter + instructions
├── references/        optional supporting docs
└── templates/         optional templates

SKILL.md starts with frontmatter that names the skill and says when to use it:

yaml

---
name: my-skill
description: When to reach for this skill.
---

# My Skill

Instructions, conventions, patterns...

The skill Empryo shipsLink to this section

Empryo installs one skill of its own, called empryo, at ~/.empryo/skills/empryo/SKILL.md. It teaches an agent to answer questions about Empryo from the current documentation and to change your Empryo settings safely. It includes a map of the docs, so the agent reads the right page instead of guessing.

This skill updates itself between releases. At most once every six hours, when Empryo starts, it checks the published skill index and installs a newer version if there is one. The download must match the checksum published in the index, and the version in the file must match too.

Empryo only replaces a copy you have never edited. If you edit the skill or delete it, your change stays.

To stop the update check and keep the version that came with your installed app, set:

json

{ "liveSkills": false }

RemoveLink to this section

In the Installed tab, select a skill and delete it. Empryo removes its folder from disk.

Writing your ownLink to this section

Any folder with a SKILL.md is a skill. Put one at .empryo/skills/my-skill/SKILL.md (this project) or ~/.empryo/skills/my-skill/SKILL.md (all projects) and it appears in the Installed tab.

When the skill is active, the agent reads its whole content, so keep SKILL.md short and specific.