The SKILL.md file schema

This page describes the Skills format that the current version of Explyt reads. General information and creating a Skill through the interface are covered on the Skills page.

Where Explyt looks for Skills

Each Skill lives in its own directory:

<configuration root>/skills/<skill-name>/SKILL.md

The main configuration roots are:

• <project root>/.explyt for project Skills;
• ~/.explyt for global Skills available in every project;
• recognized dot directories of other tools, such as .claude, if they contain a skills directory.

Explyt reads only one level of directories inside skills. The file skills/team/refactor/SKILL.md is not treated as a Skill, because there are two directories between skills and SKILL.md.

Minimal file

SKILL.md consists of YAML front matter and a Markdown instruction:

---
name: refactor
description: Reviews a refactoring plan and carries it out in small steps
---

First study the declarations and usages of the symbols being changed.
After each step, run the appropriate check and review the diff.

Required fields:

Field	Type	Constraints
name	string	1 to 50 characters; Latin letters, digits, _ and - are allowed: [A-Za-z0-9_-]{1,50}
description	string	Briefly explains to the agent which tasks the Skill is for

name is needed for manual invocation with /skill-name and for resolving collisions. Choose a short, stable name if the Skill will be invoked manually or referenced from working instructions. After creating the file, type / in the chat and make sure the Skill is found under that name.

The agent reads description when selecting a Skill automatically. Describe not only the action but also the situation that triggers it, for example: "Checks database migrations before a merge". Once you have saved the file, give the agent a suitable task and check that it proposes or invokes the right Skill. General ways to create and run Skills are described on the Skills page.

The schemaVersion field is optional. If it is absent, Explyt uses version v0.1.

schemaVersion: v0.1
name: refactor
description: Reviews and performs a refactoring

Recognized fields

The parser also knows the following fields. Do not rely on the mere presence of a field: some of them exist for compatibility with other tools' formats and do not change Explyt's behavior yet.

Field	Format or state in Explyt
schemaVersion	String; optional, default value v0.1
allowed-tools	String or list; read, but currently does not restrict the Skill's tools
argument-hint	Accepted for compatibility, the behavior is ignored
disable-model-invocation	Accepted for compatibility, the behavior is ignored
user-invocable	Accepted for compatibility, the behavior is ignored
model	Accepted for compatibility, the behavior is ignored
context	Accepted for compatibility, the behavior is ignored
hooks	Accepted for compatibility, the behavior is ignored
tags	Accepted for compatibility, the behavior is ignored
content	Recognized by the parser, but the field's behavior is ignored; write the instruction in the Markdown body of the file
agent	An Explyt extension: the agent mode for launching the Skill manually from the catalog or with /skill-name
used-by	An Explyt extension: the list of modes allowed to invoke the Skill automatically

For a portable Skill, name, description and a Markdown body are enough. Do not use fields with unpublished behavior for access restrictions or other critical settings. The available actions are determined by the mode and tool permissions.

Explyt extensions: agent and used-by

agent: the mode for manual invocation

The agent field applies when the Skill is launched from the catalog or with /skill-name in the chat.

• Omit agent if the Skill should run with the standard Code agent. This suits a general-purpose short procedure that does not need another mode's specialization.
• Specify a concrete mode if manual invocation always needs that specialization. For example, set agent: Orchestrator for a multi-step scenario: Orchestrator will control the sequence and bring in specialized subagents.

To verify the setting, launch the Skill with /skill-name and make sure Explyt opened the expected mode.

used-by: automatic Skill selection

The used-by field controls only the automatic selection of a Skill by agents. Manual invocation from the catalog or with /skill-name stays available.

• Omit the field if the standard Code agent should pick up the Skill automatically. Use this option for a general everyday development procedure.
• Set an empty list, used-by: [], if the Skill should only be launched manually. This suits a dangerous or expensive procedure that must not be selected without an explicit user command.
• List the modes if automatic invocation is only acceptable for them. For example, allow Orchestrator and General to select a multi-step Skill, but do not add modes with a narrower purpose.

After saving, check both paths: give a suitable task to an allowed agent, then invoke the Skill manually with /skill-name.

---
name: multi-step-workflow
description: Runs a multi-step scenario with the help of specialized subagents
agent: Orchestrator
used-by:
  - Orchestrator
  - General
---

The agent and used-by fields are an Explyt extension. Other tools that support the base Skills standard may ignore them. For general information about creating, storing and running Skills, see the Skills page.

How identical names are resolved

If several sources contain a Skill with the same name, Explyt keeps the variant from the source with the higher priority. Sources are loaded in the following order, from lowest priority to highest:

1. built-in Skills;
2. global Skills from recognized third-party dot directories, with directories sorted by name;
3. global Skills from ~/.explyt;
4. project Skills from recognized third-party dot directories;
5. project Skills from <project>/.explyt.

So a project Skill overrides a global one, and .explyt takes precedence over other dot directories in the same scope. On a collision, the interface does not merge the contents of the two Skills.

Use a matching name deliberately, when a project needs a local version of a global or built-in Skill. Copy the Skill to <project>/.explyt/skills/<directory>/SKILL.md, keep the original name and adapt the instruction to the repository's conventions. Then invoke /skill-name and check that the project version runs. In all other cases, choose unique names so that the source of a Skill is obvious.

Loading errors

A Skill fails to load if:

• SKILL.md has no YAML front matter;
• the YAML contains a syntax error or has an invalid structure;
• a required field is missing;
• a field value fails schema validation, for example name is longer than 50 characters;
• the file is deeper than one directory inside skills.

Explyt reports the path of the problematic field. For YAML and structural errors, the message may also contain the line and column. Open the Error group in the Skills list and hover over the error, then fix the file and invoke /skill-name again.

Related pages

• Skills
• Configuration troubleshooting
• Active configuration
• Permissions and safety