Skill Authoring Reference

A skill is a named prompt snippet the agent can invoke. It lives in a SKILL.md file with YAML front matter and a body. This page is the reference for the format. The authoritative source is docs/skills.md in the engine repository.

File format

---
name: run-tests
description: Run tests for a specific module
---

Run the test suite for module: $ARGUMENTS

The front matter identifies and configures the skill; the body is the prompt that gets substituted in when the skill is invoked.

Front matter keys

Key	Description
`name`	Unique identifier used to invoke the skill.
`description`	One-line summary shown in the skill list.
`allowed-tools`	Optional. Restricts the skill to the listed tools (kebab-case key).
`argument-hint`	Optional. Hint string shown for the skill’s arguments.
`when-to-use`	Optional. Guidance on when the skill should fire.
`version`	Optional. Skill version string.
`model`	Optional. Override the active model for this skill.
`effort`	Optional. Reasoning effort: `low`, `medium`, `high`, or `max`.
`paths`	Optional. Globs that gate when the skill is active.
`shell`	Optional. Shell for command expansion (`bash` only).

Per-skill tool restriction uses allowed-tools. There is no permissions front matter field; global allow and deny lists live in config under [tools.skills].

Variables

The body supports variable substitution:

Variable	Expands to
`$ARGUMENTS`	The full argument string passed to the invocation.
`$0`, `$1`, …	Individual positional arguments.
`${WCORE_SKILL_DIR}`	The directory the skill file lives in, for referencing sibling files.

Shell expansion

A skill can run a shell command and inline its output using backtick-bang syntax:

Current branch: !`git branch --show-current`

The command runs when the skill is invoked and its output replaces the expression.

Load order

Skills are discovered from several locations, highest priority first, with the first match winning on duplicate names: bundled skills compiled into the binary, then skills from MCP servers, then user-global skills, then project skills in .wayland-core/skills/, then any --add-dir directories, then the legacy commands/ directory. A user-global skill overrides a project skill of the same name.

Add an extra skills directory with --add-dir, and print the resolved skill directories with --skills-path.

Lifecycle

Learned skills move through a lifecycle (staged, active, archived) you manage with --skills-audit, --skills-promote, and --skills-archive. See Skills Lifecycle.