Skills
A skill is a reusable pack of know-how — a set of instructions for a particular kind of task that the agent pulls in when the work calls for it. Where rules apply to everything you do in a project, a skill applies to a specific job: reviewing a PR, writing a migration, following your team's design system.
Two kinds of skills
- Built-in skills ship inside the agent and are applied automatically when a task matches — you don't install or invoke them.
- Your own skills are folders you add. The agent discovers them and uses the ones relevant to what you've asked.
Writing a skill
A skill is a folder containing a SKILL.md file with a short YAML frontmatter header and Markdown instructions:
---
name: pr-review
description: Review a pull request for correctness, tests, and style before approval.
category: workflow
tags: [git, review]
---
# Reviewing a pull request
When asked to review a PR:
1. Read the diff and summarize what changed and why.
2. Check that new behavior has tests; flag any that don't.
3. Look for missing error handling, especially around I/O and user input.
4. Note anything that violates the conventions in AGENTS.md.
5. End with a clear verdict: approve, or the specific changes needed.
The description matters most — it's how the agent decides when the skill is relevant, so make it concrete.
Where skills live
The agent looks for <name>/SKILL.md folders in these places:
| Location | Scope |
|---|---|
./.lily/skills/ | Project (this repo) |
~/.lily/skills/ | Global (all projects) |
./.agents/skills/ | Project (shared agent-skills convention) |
Put project-specific skills under ./.lily/skills/ and commit them so your team shares them; put personal skills you want everywhere under ~/.lily/skills/. Skills follow the standard Agent Skills format, so packs you already keep for other compatible tools are picked up automatically the first time.
Seeing what's loaded
In the interactive terminal UI, list the skills currently available with:
/skills
The agent can also manage skills itself while it works — loading, listing, and re-reading them as a task requires — and it may write its own "learned" skills when it discovers a repeatable procedure.
See also
- Rules & instructions — standing instructions for a project.
- Tools — what the agent can do while following a skill.