Skills

A Skill is a reusable set of Markdown instructions in SKILL.md. It gives the model a task-specific method rather than adding another hard-coded tool. In the unified Extensions model, Skill is one of three kinds alongside Plugin and Mcp.

For discovery and installation, use the Extensions Store. This page is about the authoring contract and runtime behavior of SKILL.md.

Authoring contract

A skill is a directory containing a required SKILL.md:

~/.aleph/skills/code-review/SKILL.md
.aleph/skills/project-review/SKILL.md

Project skills may also be discovered from .claude/skills/. Plugin-bundled skills live under a plugin's skills/ directory and are folded into the same SkillSystem index.

The frontmatter must contain:

• name — the human-readable name and the basis for the runtime skill ID
• description — one concise routing description

The Markdown body is the complete instruction set loaded after the model selects the skill. The parser derives an ID by lowercasing name, joining whitespace with hyphens, and resolving duplicates by source priority.

Writing descriptions and trigger words

description is the primary router. It should say what the skill does, when it applies, the important input or output, and the boundaries that keep nearby requests out. Put the words and phrases users actually use in that sentence. There is no supported triggers frontmatter field in the current SkillManifest; do not maintain a separate keyword list.

Use when-to-use when a concise proactive hint adds information that does not fit naturally in the description:

---
name: code-review
description: Review changed source code for correctness, security, performance, and maintainability; use for code review, reviewing a patch, or checking a pull request.
when-to-use: When code has been written or modified and needs an independent quality review
scope: system
user-invocable: true
disable-model-invocation: false
---

Review the changed code systematically and report concrete findings with file and line references.

when-to-use is emitted as <when> in the model's available-skill catalog. Matching is semantic and model-led; Aleph does not run a deterministic BM25 or edit-distance trigger engine. When the request matches the hint, the model is instructed to load the skill proactively rather than wait for the user to name it.

Optional frontmatter

The current SkillSystem parser accepts these optional fields:

Example dependency metadata:

eligibility:
  required-bins:
    - git
  required-env:
    - GITHUB_TOKEN
install:
  - id: git
    kind: brew
    package: git
    bins:
      - git

enabled: false makes a skill ineligible. always: true skips the other eligibility checks, but does not override an explicit disable. Unknown prompt scopes fail closed to disabled.

Markdown CLI compatibility

The compatibility Markdown CLI reader also understands metadata.requires.bins, metadata.aleph.security, metadata.aleph.input_hints, and Docker settings. Those fields describe the legacy CLI execution path; new SkillSystem skills should use the top-level fields above for eligibility and dependency installation. A security declaration is not a replacement for Aleph's runtime approval and install gates.

Keep the body lean

Use progressive disclosure:

1. Keep SKILL.md focused on routing, rules, and the normal workflow.
2. Put deep reference material in files such as references/guide.md.
3. Put deterministic helper code in scripts/ when appropriate.
4. Ask the model to use skill_read(skill_id, file_name=...) for supporting text.

The skill_read path is containment-checked, size-bounded, and expands the skill-relative context. Do not teach a skill to read its own Markdown resources with a raw absolute path or shell cat. The absolute location returned by skill_read is for executing a referenced script, not for bypassing the reader.

A declared automation block is only a suggestion. After installation the model may ask for consent and create a job with cron_manage; installing a skill never schedules work silently.

Discovery and precedence

The shared SkillSystem scans configured roots and plugin-published roots without a restart. Source priority is:

1. Workspace
2. Plugin
3. Global
4. Bundled

A higher-priority skill replaces a lower-priority duplicate. Symlinked or duplicate paths are resolved by precedence rather than rejected as ambiguous. Installed-plugin skills appear in the same index and are readable through skill_read.

Prompt representation

Model-visible skills are injected as compact XML:

<available_skills>
  <skill>
    <name>Code Review</name>
    <description>Review changed source code for correctness and security</description>
    <when>When code has been written or modified and needs quality review</when>
    <version>sha256:a1b2c3d4</version>
  </skill>
</available_skills>

<when> is omitted when no hint is declared. The version is a short digest of the instruction body. If it changes after a previous read, the model must call skill_read again. Prompt budgets may keep the name, trigger hint, and version while moving descriptions and bodies to deferred loading; skill_list remains the fallback for enumeration.

Install-time safety

Third-party skill bundles are scanned before registration. The guard covers prompt-injection phrases, invisible Unicode, credential paths, reverse shells, destructive commands, download-and-execute patterns, and oversized files. Community findings at the caution level are blocked; dangerous content is blocked for untrusted sources, while bundled content follows the built-in trust policy. The scan is a defense-in-depth check, not a general sandbox.

Management surface

The built-in tools are:

• skill_list — discover skill metadata and supporting files
• skill_read — load SKILL.md or a contained supporting file
• skill_status — inspect eligibility, missing requirements, source, and usage
• skill_install — install a declared dependency
• skill_manage — create, edit, configure, or remove skills

The corresponding gateway methods include skills.status, skills.update, skills.install_dep, and skills.remove. Extension installation routes a Skill entry through the same SkillSystem rather than a separate store-specific skill registry.

Related pages

• Skill System — runtime lifecycle and data model
• Extensions — plugin host and plugin-bundled skills
• Extensions Store — unified discovery and trust-gated installation
• Capability System — extension declarations and runtime ledgers