Skill System

The skill module is the bounded context that loads Markdown skills and exposes one shared runtime to the agent loop, plugin host, gateway, and Panel. It owns parsing, source precedence, eligibility, snapshots, prompt rendering, dependency installation, status, usage, and hot reload.

The user-facing Skill kind is routed to this subsystem by the unified Extensions façade. It is not a second implementation beside the Extensions Store.

Runtime architecture

SkillSystem
├── SkillRegistry
├── SkillSnapshot
├── EligibilityService
├── SkillsConfig
├── InstallExecutor
├── status and usage stores
└── broadcast events

SkillSystem is cheaply cloneable and the process-wide shared instance is used by the extension manager and built-in skill tools.

pub struct SkillSystem {
    registry: SkillRegistry,
    snapshot: SkillSnapshot,
    eligibility: EligibilityService,
    config: SkillsConfig,
}

Initialization scans the supplied roots, atomically replaces the registry, rebuilds the snapshot, and emits lifecycle events. A file reload replaces one manifest and rebuilds the snapshot without restarting the daemon.

Skill manifest model

The current domain aggregate contains:

SkillManifest
├── id, name, description
├── content
├── scope and bound_tool
├── eligibility
├── install specifications
├── invocation policy
├── source
├── primary_env, homepage, emoji
├── when_to_use
└── automation

The Markdown parser requires name and description. It accepts when-to-use and maps it to when_to_use; it does not create a deterministic trigger matcher from a triggers list. The body remains model instructions, while frontmatter supplies routing and runtime metadata.

SkillSource is Bundled, Global, Plugin, or Workspace. Its precedence is Bundled < Global < Plugin < Workspace. The registry keeps the highest-priority manifest for a duplicate ID. Plugin skills are published into the shared scan roots and therefore participate in the same snapshot and skill_read resolution.

Eligibility evaluation

EligibilityService evaluates a manifest against the current configuration in this order:

1. An explicit enabled: false returns Disabled.
2. always: true returns eligible.
3. The current operating system is checked.
4. Every required-bins entry must resolve on PATH.
5. At least one any-bins entry must resolve when the list is non-empty.
6. Every required-env variable must be present.
7. Every required-config dotted path must exist in the configuration snapshot.

A status entry reports eligible, disabled, missing binaries, environment variables, and configuration keys. Results from skill_status and full_status are sorted by skill ID for deterministic clients.

Prompt injection and deferred loading

Only model-visible skills enter the prompt snapshot. scope: disabled and disable-model-invocation: true exclude a skill from the catalog. scope: system is the default; tool is bound to an available tool; standalone is available for explicit invocation.

The prompt builder emits <available_skills> entries containing the name, description, optional <when> hint, and a content version digest:

<available_skills>
  <skill>
    <name>Code Review</name>
    <description>Review changed source code</description>
    <when>When code has been written or modified</when>
    <version>sha256:a1b2c3d4</version>
  </skill>
</available_skills>

The model is told to call skill_read before relying on a skill's body, to call skill_list when it needs discovery, and to invoke a matching <when> skill proactively. Supporting files are read by passing a skill-relative file_name to skill_read.

Prompt budgets limit the number of entries and the characters spent on full descriptions. Over-budget entries degrade to name, optional trigger hint, and version rather than making the whole skill library invisible; a count cap adds a note directing the model to skill_list.

Installation and configuration

Per-skill enablement and scope overrides, dependency preferences, and prompt budgets are persisted in:

~/.aleph/data/skills.toml

InstallExecutor chooses a current-OS install specification and supports brew, apt, scoop, winget, npm, uv, go, and URL downloads. Package and path arguments use a strict allowlist, and downloads require an HTTP or HTTPS URL without traversal segments.

The built-in management tools are:

skills.install is the compatibility gateway for Git, ZIP, and local Markdown skill bundles. It scans a community bundle before registering it. The unified extensions.install path resolves a Hub Skill entry and routes the resulting install through the same backend.

Lifecycle and updates

scan → parse → register → evaluate → snapshot → prompt
                         └──────────────→ status

Directory rescans replace the registry atomically. skill_manage mutations rebuild the snapshot immediately. Usage and lifecycle data are kept in the skill directory sidecar and are reported by full_status; bundled skills cannot be removed through the SkillSystem.

When an instruction body changes, its content digest changes. The model must re-read it before using a cached body. This keeps model-visible metadata cheap while preserving fresh instructions.

Security boundary

Skill scanning and dependency installation are separate controls. The install-time scanner checks every readable bundle file with a per-file size limit and classifies findings as safe, caution, or dangerous. The trust level determines whether a finding may proceed. Runtime tool execution still passes through Aleph's scoped tool, approval, and sandbox controls.

Code locations

• src/skill/mod.rs — shared SkillSystem
• src/skill/manifest.rs — SKILL.md parser
• src/skill/registry.rs — precedence-aware registry
• src/skill/snapshot.rs — model-visible snapshot
• src/skill/eligibility.rs — eligibility evaluation
• src/skill/prompt.rs — XML prompt and budgets
• src/skill/installer.rs — dependency installation
• src/skill/status.rs — status projection
• src/skill/guard.rs — install-time scanning

Related pages

• Skills — authoring contract and trigger hints
• Extensions — plugin integration
• Extensions Store — unified installation
• Capability System — declarations, permissions, and runtime ledgers