Skill System

The skill module implements Skill System v2, a domain-driven runtime for managing skills. It handles skill registration, eligibility evaluation, SKILL.md parsing, prompt injection, and lifecycle management.

Design Philosophy

1. Domain-driven — Skills are first-class domain objects with manifests, eligibility rules, and lifecycle states
2. Declarative — Skills declare their capabilities in SKILL.md files; the system evaluates when to use them
3. Hot-reloadable — Skills can be added, updated, or removed without restarting

Core Components

SkillSystem

Unified facade for the rest of the application:

pub struct SkillSystem {
    registry: SkillRegistry,
    eligibility: EligibilityService,
    installer: InstallExecutor,
}

impl SkillSystem {
    pub async fn init(&self,
    ) -> Result<()> { /* ... */ }

    pub async fn rebuild(&self,
    ) -> Result<()> { /* ... */ }

    pub fn skill_status(&self,
    ) -> Vec<SkillStatusEntry> { /* ... */ }
}

Determinism: skill_status() and full_status() return results sorted by skill ID.

SkillRegistry

Maintains the set of known skills:

pub struct SkillRegistry {
    skills: HashMap<SkillId, SkillSnapshot>,
}

Skill Manifest

Parsed from SKILL.md frontmatter:

pub struct SkillManifest {
    pub id: SkillId,
    pub name: String,
    pub description: String,
    pub triggers: Vec<String>,
    pub eligibility: EligibilityRules,
}

EligibilityService

Determines whether a skill can be used in the current context:

pub struct EligibilityService;

impl EligibilityService {
    pub fn check(
        &self,
        skill: &SkillManifest,
        context: &ExecutionContext,
    ) -> EligibilityResult { /* ... */ }
}

Ineligibility reasons:

• Missing dependencies
• Unsupported platform
• Missing environment variables
• Conflicting skills

Skill Commands

Skills can expose CLI-style commands:

pub struct SkillCommandSpec {
    pub name: String,
    pub description: String,
    pub args: Vec<CommandArg>,
}

Resolution: When multiple skills define the same command name, workspace skills override bundled skills (sorted by priority, then ID for tie-breaking).

InstallExecutor

Installs skills from external sources:

pub struct InstallExecutor;

impl InstallExecutor {
    pub async fn install(
        &self,
        spec: &InstallSpec,
    ) -> Result<InstallResult> { /* ... */ }
}

Security: Uses strict allowlist for package names — only [a-zA-Z0-9\-_./:@+=~] permitted. Blocks spaces, quotes, redirections, backticks, $(), and all shell metacharacters.

Prompt Injection

Skills are injected into the system prompt as XML:

pub fn build_skills_prompt_xml(
    skills: &[SkillSnapshot],
) -> String

<skills>
  <skill id="code-review" name="Code Review">
    <triggers>
      <trigger>review code</trigger>
      <trigger>check this</trigger>
    </triggers>
    <instructions>
      When reviewing code, check for: ...
    </instructions>
  </skill>
</skills>

Lifecycle

Discovered → Evaluated → Eligible → Loaded → Active
                ↓
            Ineligible

States:

• Discovered — Found in filesystem
• Evaluated — Eligibility checked
• Eligible — Can be used in current context
• Loaded — Parsed and ready
• Active — Currently available to the agent

Safety Properties

• No command injection — Strict allowlist for package names
• Deterministic ordering — Skills sorted by ID for reproducible output
• No unwrap in production — All error paths return Result
• Lock safety — Uses tokio::sync::RwLock (no poisoning)

Code Location

• src/skill/mod.rs — SkillSystem facade
• src/skill/registry.rs — Skill registry
• src/skill/eligibility.rs — Eligibility evaluation
• src/skill/manifest.rs — SKILL.md parsing
• src/skill/installer.rs — Skill installation
• src/skill/commands.rs — Command resolution
• src/skill/prompt.rs — Prompt injection
• src/skill/status.rs — Status tracking
• src/skill/snapshot.rs — Skill snapshots

See Also

• Skills — Conceptual overview of skills
• Extensions — Plugin architecture
• ClawHub — Skill registry integration