SKILL.md and frontmatter

Applies to: StablEdge Desktop 0.4.4 and later

Every Skill directory needs a SKILL.md at its root. It has two parts: the YAML frontmatter wrapped in --- at the start, and the Markdown body that follows.

---
name: release-notes
description: "Use when organizing release notes: group commits into the three sections New, Improved, and Fixed. Trigger phrases: release notes, version notes, changelog."
---

# Release notes

1. First read the commit list for this release...
2. ...

File format requirements

• The file name must be SKILL.md (same case) and the encoding must be UTF-8.
• The first character of the file must be ---. A file with a BOM is reported as "missing frontmatter".
• The frontmatter must be a valid YAML key-value mapping and must contain name.
• Skills that do not meet the requirements are not loaded. For Skills in the install directory, StablEdge records the diagnostic reason, such as SKILL_MD_NO_FRONTMATTER, SKILL_MD_YAML_INVALID, SKILL_MD_NAME_MISSING, SKILL_MD_METADATA_INVALID, or SKILL_MD_DUPLICATE_NAME, so you can find what broke.

Field reference

Fields outside this table are kept as they are but not used by StablEdge, except for the network domain declarations mentioned below.

Naming rules

StablEdge validates name as follows:

• After trimming leading and trailing whitespace, it may contain only letters (including Chinese and other Unicode characters), digits, -, _, ., and spaces;
• A single space is converted to -, while consecutive whitespace characters make the name invalid; the converted result must not exceed 80 characters;
• It cannot be empty, and it cannot be . or ..;
• On install, the converted result becomes the directory name, so My Skill is installed to My-Skill/.

The rules allow a fairly wide range, but to be clear and stable everywhere, we recommend:

• Use only lowercase letters, digits, and hyphens (hyphen-case), for example release-notes;
• Use a short phrase that starts with an action, adding a tool prefix when needed, for example gh-address-comments;
• Keep the directory name the same as name;
• Do not reuse the name of an installed Skill or a built-in Skill. The duplicate copy is ignored.

Writing a description

description is the main basis for a Skill being selected. The Agent can see only this field before it loads the body, so "when to use it" must be written here, not in the body.

StablEdge searches with lightweight keyword matching, without vectors or models:

• Search: the query is split into words by whitespace and punctuation (including the Chinese comma, full stop, and enumeration comma); each word that hits the name adds 8 points, a hit in description adds 3 points, and a hit in paths adds 2 points;
• Automatic matching: description is split into fragments by the same rules; if any fragment (at least 2 characters) appears in the user message, it counts as a match.

A good description should therefore:

1. Start with one sentence on what it does and which situations it fits;
2. List the trigger phrases users really say, separated by enumeration commas or commas, keeping each one short;
3. State the situations it does not fit, so it does not compete with neighboring Skills for tasks;
4. Make the purpose clear within the first 80 characters, because the list view shows only the first 80;
5. Be wrapped in double quotes, and contain no angle brackets.

You can use the built-in pdf Skill as a reference (excerpted from builtin/pdf/SKILL.md):

description: "Use when the user needs to create, read, analyze, or manipulate PDF documents. Trigger phrases: PDF, pdf file, read PDF, extract PDF, merge PDF, PDF to text, and so on. Not for Word documents, spreadsheets, or presentation tasks."

paths: activate by file path

A Skill with paths set is a conditional Skill: when a file path involved in the conversation (relative to the Workspace) matches these patterns, it is activated automatically. Patterns use gitignore syntax, so for example *.pdf matches PDFs in any directory.

paths:
  - "*.pdf"

paths controls automatic activation only. A conditional Skill still appears in the Skill catalog, and the Agent can search and load it at any time.

context: inline and fork

The default inline hands the body to the Agent in the current conversation. context: fork requires the Skill to run in an isolated asynchronous environment, with the result returned to the current conversation; when the runtime does not support isolated execution, loading fails outright and does not fall back to inline. Do not set this field for Skills that do not clearly need isolated execution.

Variables in the body

When a Skill is loaded, the following variables in the body are replaced:

Unknown variables are kept as they are. Note that the Agent cannot reach the Skill directory directly with the general file tools, so when you reference bundled files, write relative paths and let the Agent read them through the skill tool; see Resources and scripts.

Declare the network domains a script needs

If a Skill's scripts need network access, you can declare domains in the frontmatter as the default network allowlist for script runs. StablEdge accepts the following common forms (pick one):

network:
  hosts:
    - api.example.com
# or
permissions:
  network:
    hosts:
      - api.example.com
# or
allowed-hosts:
  - api.example.com

These declarations are candidates only: users see them when confirming a script run, and the Agent can also specify them explicitly at call time or pass an empty list to run offline. See Running scripts.