Skills

A skill is a playbook in a SKILL.md file: how your team reviews a migration, cuts a release or writes a changelog entry. The agent sees each skill’s name and description, and loads the full text only when a task calls for it, so a long skill costs nothing until it is used.

Write a skill

One folder per skill, with a SKILL.md in it:

.agents/skills/ is where Codex, OpenCode, Pi, GitHub Copilot and the npx skills installer put skills, so one installed for any of them works here too. Luxe reads a repository’s .agents/skills/ from the top of the repository down to the project. When two skills share a name, whatever its case, the one lower in the table wins, so a project’s skill replaces your own, and between nested .agents/skills/ folders the deeper one wins. A skill reached twice through a symbolic link counts once.

---
name: release-notes
description: >
  Writes the CHANGELOG entry for a user-visible change. Use when a change
  adds, removes or alters something a user would notice.
---

1. Read the diff and the issue it closes.
2. Add one line under `## Unreleased` in CHANGELOG.md, in the past tense,
   naming what changed for the user, not how.
3. Link the pull request at the end of the line.

Write the description for the moment the agent decides whether to load it: say when to use it, not what it contains. Without one, the agent sees only the name. name is optional and defaults to the folder’s, and the --- block has to start on the first line.

A skill folder can also hold reference files. A loaded skill tells the agent its folder, so a skill that says see references/schema.md gets read. A skill over 40,000 characters is cut off, with a note telling the agent to read the rest of the file.

Use a skill

The agent loads a skill when its description fits the task. To ask for one yourself, mention it: @, tab to Skills, and enter, as in split this into a stack with @[skill:gh-stack].

Project context lists the skills Luxe found: type skills on the start screen and open it. A SKILL.md placed directly in skills/, without its own folder, is skipped, and Luxe names it at startup. The list in the agent’s instructions is read with a session’s first message, and again when you resume one. The @ picker and the skill tool look again every time, so a skill added mid-session can be mentioned or loaded at once.

Install a skill

Skills written for other agents use the same format and work as they are. Installing one is copying its folder:

git clone --depth 1 https://github.com/github/gh-stack /tmp/gh-stack
mkdir -p ~/.config/luxe/skills
cp -r /tmp/gh-stack/skills/gh-stack ~/.config/luxe/skills/

Create skills/ first, as above. Without it, cp -r copies the skill’s contents to skills/ itself, one level too high.

A skill’s text reaches the model as instructions, so read a skill before installing it, as you would a script. The same goes for a repository you clone: its .agents/skills/ and .luxe/skills/ reach the model without --trust-project. Luxe removes comments and invisible characters from skill files, as it does from AGENTS.md, but without a notice.