Files
luxe/docs/guide/skills.md
Evan Whittaker a0666d6c81 luxe 0.1.4: remembered models, wheel-driven lists, and a steadier phone app
- luxe starts on the model you last chose in this project, then the last one anywhere. Signing in
  opens the model picker instead of choosing for you.
- Every list in a modal takes the mouse wheel and a draggable scrollbar.
- The phone app shows reasoning in full, stays put while you read back through a long session, and
  shows a question's answer on its card.
- On Windows, luxe update replaces the running luxe, and a signed-in install no longer sees setup
  again.
- The file tree no longer shows "engine busy" in a large project, loop output is easier to follow,
  and the name is written lowercase.

The CHANGELOG has the full list.
2026-10-20 13:51:34 -05:00

82 lines
3.7 KiB
Markdown

---
title: "Skills"
summary: "Teach the agent a procedure it loads only when it needs it."
order: 2
group: "Extend"
---
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:
| Folder | For |
| --- | --- |
| `~/.agents/skills/<name>/` | Every project, and every agent that reads it |
| `~/.config/luxe/skills/<name>/` | Every project (`%APPDATA%\luxe\skills` on Windows) |
| `.agents/skills/<name>/` | This repository, committed with it |
| `.luxe/skills/<name>/` | This project. Git sees it too, since `.luxe/` keeps `skills/` out of what it ignores. |
`.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.
```markdown title=".luxe/skills/release-notes/SKILL.md"
---
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:
```bash
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`](project-context.md#what-luxe-removes),
but without a notice.