Skip to content
Wayland Docs

Skills

A skill is a named prompt snippet the engine can invoke on demand. Skills let you package reusable instructions, checklists, or tool sequences into one callable name, with variable substitution and optional model and permission overrides.

The SKILL.md format

Section titled “The SKILL.md format”

A skill is a Markdown file with YAML front matter. The minimal form needs a name and a description:

---
name: greet
description: Print a greeting
---


Hello. How can I help you today?

The fuller front matter adds conditional activation and per-skill overrides:

---
name: rust-review
description: Rust-specific code review checklist
paths:
  - "**/*.rs"          # skill is dormant unless a path matches
model: claude-sonnet-4-20250514
effort: high           # low | medium | high | max
allowed-tools:
  - Read
  - Grep
---


When reviewing Rust code, check for unwrap in library code and missing doc comments.

A skill with paths is dormant by default and appears in the prompt only when the working path matches one of its globs.

Per-skill tool restriction is done with allowed-tools (the kebab-case key above). There is no permissions block in skill front matter; global allow and deny lists live in config under [tools.skills].

Recognized front matter keys include name, description, allowed-tools, argument-hint, arguments, when-to-use, version, model, effort, context, agent, paths, shell, user-invocable, hide-from-slash-command-tool, hooks, and type.

Variables and shell expansion

Section titled “Variables and shell expansion”

Inside the body, the engine substitutes runtime variables and expands inline shell commands:

VariableReplaced with
$ARGUMENTSThe full argument string passed to the skill.
$0, $1, …The individual positional arguments ($0 is the first).
${WCORE_SKILL_DIR}Absolute path to the skill’s directory.
${WCORE_SESSION_ID}Current session ID, when sessions are enabled.

Lines containing !`cmd` run cmd and substitute the output:

Current branch: !`git rev-parse --abbrev-ref HEAD`

Shell expansion is disabled for skills sourced from MCP servers, to keep untrusted sources from running commands.

Load order

Section titled “Load order”

Skills load from these locations, highest priority first, with the first match winning on duplicate names:

  1. Bundled skills compiled into the binary
  2. Skills from MCP servers
  3. <config_dir>/wayland-core/skills/ (user-global)
  4. .wayland-core/skills/ (project-local, checked in)
  5. Directories passed with --add-dir
  6. .wayland-core/commands/ (legacy flat .md files)

A user-global skill overrides a project skill of the same name.

Each skill is a SKILL.md inside a named subdirectory. A small set of skills is compiled into the binary; these are always available and are never dropped to fit the prompt budget. Run wayland-core --skills-path to print the directories being scanned and whether each exists on disk.

Next

Section titled “Next”