Skills

How Aleph's skill system enables reusable capabilities through SKILL.md definitions, prompt injection, and slash command integration.

Skills are reusable capabilities defined by markdown-based SKILL.md files. Unlike static tool definitions, skills provide natural language instructions that guide the LLM's behavior for specific tasks.

What is a Skill?

A skill in Aleph consists of:

SKILL.md — A markdown file describing when and how the skill should be used, written in natural language for the LLM to interpret
Manifest — Structured metadata parsed from SKILL.md frontmatter (name, description, triggers)
Optional tooling — Skills can invoke built-in tools, WASM plugins, or Node.js extensions

Skills are discovered from skill directories and loaded at runtime:

~/.aleph/skills/
├── code-review/
│   └── SKILL.md
├── git-commit/
│   └── SKILL.md
└── translate/
    └── SKILL.md

Skill System Architecture

SkillSystem (facade)
  ├── SkillRegistry — Stores loaded skill manifests
  ├── SkillSnapshot — Immutable view for prompt building
  ├── EligibilityService — Determines which skills apply
  └── Events — Broadcast skill system changes

Core Components

SkillSystem

The main entry point, cheaply cloneable via Arc:

// src/skill/mod.rs
pub struct SkillSystem {
    inner: Arc<Inner>,
}

struct Inner {
    registry: RwLock<SkillRegistry>,
    snapshot: RwLock<SkillSnapshot>,
    eligibility: EligibilityService,
    config: RwLock<SkillsConfig>,
    // ...
}

impl SkillSystem {
    pub async fn init(&self, 
        dirs: Vec<PathBuf>
    ) -> Result<(), SkillSystemError>;
    
    pub async fn current_snapshot(&self
    ) -> SkillSnapshot;
}

Skill Registry

Maintains the collection of loaded skills:

// src/skill/registry.rs
pub struct SkillRegistry {
    skills: HashMap<SkillId, SkillManifest>,
}

impl SkillRegistry {
    pub fn register(&mut self, 
        manifest: SkillManifest
    );
    
    pub fn get(&self, 
        id: &SkillId
    ) -> Option<&SkillManifest>;
}

Skill Manifest

Parsed from SKILL.md frontmatter:

// src/domain/skill.rs
pub struct SkillManifest {
    pub id: SkillId,
    pub name: String,
    pub description: String,
    pub triggers: Vec<String>,
    pub tools: Vec<String>,
    pub prompt: String,
}

Eligibility Service

Determines which skills are relevant for a given context:

// src/skill/eligibility.rs
pub struct EligibilityService;

impl EligibilityService {
    pub fn evaluate(
        &self,
        skills: &[SkillManifest],
        context: &Context,
    ) -> Vec<EligibilityResult>;
}

Prompt Builder

Injects eligible skills into the system prompt:

// src/skill/prompt.rs
pub fn build_skills_prompt_xml(
    snapshot: &SkillSnapshot,
    eligible: &[SkillId],
) -> String;

Skills are formatted as XML in the prompt:

<skills>
  <skill id="code-review">
    <description>Review code for bugs and style issues</description>
    <instructions>
      When the user shares code, analyze it for:
      - Logic errors
      - Security vulnerabilities
      - Performance issues
    </instructions>
  </skill>
</skills>

Skill Loading Flow

Scan — Discover SKILL.md files in configured directories
Parse — Extract frontmatter and body from each file
Register — Add to SkillRegistry with unique IDs
Snapshot — Build immutable SkillSnapshot for queries
Inject — Eligible skills injected into LLM prompt

SKILL.md Format

---
id: code-review
name: Code Review
description: Review code for bugs and improvements
triggers:
  - code review
  - review this
tools:
  - file_read
---

When the user shares code, analyze it systematically:

1. Check for logic errors and edge cases
2. Identify security vulnerabilities
3. Suggest performance improvements
4. Note style inconsistencies

Always provide specific line references when possible.

Configuration

Skills are configured in ~/.aleph/data/skills.toml:

[skills]
enabled = true
auto_match = false  # Require explicit activation

[[skills.directories]]
path = "~/.aleph/skills"
priority = 1

Slash Commands

Skills can define slash commands for direct invocation:

// src/skill/commands.rs
pub fn resolve_command(
    input: &str,
    skills: &SkillSnapshot,
) -> Option<SkillCommandSpec>;

Example: /code-review activates the code-review skill for the current session.

Module Structure

Module	Purpose
`commands`	Slash command resolution
`compat`	Backward compatibility
`config`	Skills configuration
`eligibility`	Context-based skill filtering
`events`	Skill system events
`installer`	Skill installation
`manifest`	SKILL.md parsing
`prompt`	Prompt XML generation
`recaller`	Skill recall tracking
`registry`	Skill registration
`snapshot`	Immutable skill views
`status`	Skill status tracking
`tools`	Skill tool integration

Code Location

src/skill/mod.rs — SkillSystem facade
src/skill/registry.rs — SkillRegistry
src/skill/eligibility.rs — EligibilityService
src/skill/prompt.rs — Prompt XML builder
src/skill/manifest.rs — SKILL.md parser
src/skill/commands.rs — Slash command resolver
src/domain/skill.rs — Core skill types