Skills

A skill is a self-contained capability shipped as a directory: a SKILL.md (Markdown body + YAML frontmatter) plus any companion files the skill needs at runtime. The frontmatter declares how the skill is invoked, which tools it can use, what arguments it accepts, and where it activates; the Markdown body is the prompt content the runtime expands when the skill fires.

Skills are deliberately separate from custom slash commands and plugins:

Surface	Who invokes	Tool grants	Activation
Custom command	User, by typing /<name>	None	Always.
Skill	User or model (via the skill tool)	Yes — allowed-tools	Always, or auto-activated by paths glob match.
Plugin	Bundles tools / hooks / commands	Yes	Loaded at startup if enabled.

Anatomy of a skill

.lime/skills/
└── review-pr/
    ├── SKILL.md
    └── checklist.md

SKILL.md:

---
name: review-pr
description: Run a structured review against a GitHub pull request.
when_to_use: Use when the user asks for a PR review or pastes a PR URL.
allowed-tools:
  - read_file
  - grep_search
  - "Bash(gh:*)"
argument-hint: <pr-number>
arguments:
  - pr_number
context: inline
shell: bash
version: "0.1"
---

You are reviewing PR #$pr_number against `${LIME_SKILL_DIR}/checklist.md`.

Pull the diff:

!`gh pr diff $pr_number`

Walk the checklist in order. For each item, cite the file and line.

Frontmatter fields

Field	Type	Notes
name	string	Display name. Defaults to the directory name.
description	string	Short summary, surfaced in the slash palette.
when_to_use	string	Hint that helps the model decide when to auto-invoke the skill via the skill tool.
allowed-tools	string[]	Tool permission patterns scoped to this skill, e.g. read_file, Bash(gh:*), WriteFile(./out).
argument-hint	string	Placeholder hint shown to the user (e.g. <pr-number>).
arguments	string[]	Named argument slots. Body references them as $name.
context	inline | fork	inline (default) expands into the current turn; fork runs in a sub-agent with its own budget.
agent	string	Agent type to use when context: fork. See Sub-agents.
model	string	Model override for this skill.
effort	string	Reasoning-effort override (minimal, low, medium, high).
user-invocable	bool	Whether the user can invoke directly from the palette. Default true.
disable-model-invocation	bool	Prevent the model from auto-invoking via the skill tool.
paths	string[]	Glob patterns. When the active workspace matches, the skill is auto-suggested.
shell	bash | powershell	Shell used for inline !-block execution in the body.
version	string	Skill version, surfaced in tooling.
hooks.PreToolUse	string[]	Inline hook scripts run before each tool call inside the skill.
hooks.PostToolUse	string[]	Inline hook scripts run after each tool call inside the skill.

Body substitutions

The skill’s Markdown body goes through five expansions before it becomes a turn:

1. Base directory header — a one-line Base directory for this skill: <dir> is prepended so file references resolve.
2. Argument substitution — $name is replaced with the value the caller supplied for that argument.
3. ${LIME_SKILL_DIR} — the skill’s absolute directory.
4. ${LIME_SESSION_ID} — the current session id.
5. Inline shell — !`cmd` (single-line) and fenced ```! blocks are executed under the configured shell; their output replaces the block.

Where skills are discovered

Loaded in priority order:

Scope	Path
Project	<cwd>/.lime/skills/<id>/SKILL.md
User	~/.lime/skills/<id>/SKILL.md (or $LIME_CONFIG_HOME/skills/)
Plugin	~/.lime/plugins/installed/*/skills/<id>/SKILL.md
System	*/skills/.system/<id>/SKILL.md — read-only, cannot be shadowed by user/project skills.

A skill from a higher-priority scope shadows one with the same id from a lower-priority scope.

Invoke a skill

From the palette:

/<skill-name> [args…]

From the model — the runtime exposes a skill tool the model can call:

{
  "tool": "skill",
  "input": {
    "skill": "review-pr",
    "args": "1342"
  }
}

The tool input takes skill (required, the skill name) and args (optional, a single string forwarded to the skill).

List skills

lime skills              # CLI snapshot of all loaded skills

Inside the REPL:

/skills              # interactive list / details