tests — skills

Module: tests-skills Cohesion: 0.80 Members: 0

tests — skills

This document provides a comprehensive overview of the skills module, which is central to how the application discovers, manages, and utilizes AI capabilities. It covers the core components, their interactions, and the lifecycle of a skill, with a focus on the current architecture and ongoing transitions.

Module Overview

The skills module is responsible for defining, loading, validating, and managing AI skills. These skills empower the AI agent with specific knowledge, tools, and behaviors, allowing it to perform complex tasks by leveraging external resources or specialized prompts.

Skills are primarily defined as Markdown files (SKILL.md) with YAML frontmatter, allowing for human-readable definitions alongside structured metadata. The module handles:

Core Concepts

Skill Definition (SKILL.md)

Skills are defined using Markdown files named SKILL.md. These files consist of:

Skill Tiers and Sources

Skills can originate from several sources, each with a defined priority for overriding duplicates:

The loading order (and thus override priority) is generally: agent > team > workspace > project > global > managed > bundled.

Unified vs. Legacy Skills

The skill system is undergoing a transition:

Skill Eligibility

Skills can declare prerequisites in their frontmatter using the requires field. The eligibility.js module provides functions to check:

Starter Packs

A special category of skills, identified by the starter or scaffold tag, designed to help users set up new projects or configurations. These often have aliases for easier discovery (e.g., "react" -> "typescript-react").

Architecture & Components

The skills module is composed of several key components, some representing the evolving architecture. 

graph TD
    subgraph Skill Lifecycle
        A[SKILL.md Files] --> B(SkillRegistry)
        B -- Manages --> C(UnifiedSkill Objects)
    end

    subgraph Runtime Usage
        C -- Provided to --> D(SkillManager)
        D -- Matches & Activates --> C
        C -- Checks --> E(Eligibility Module)
    end

    subgraph Remote Interaction
        F(SkillsHub) -- Installs/Publishes --> B
    end

    subgraph Legacy/Transition
        G(SkillLoader) -- Deprecated, but still loads --> C
        D -- Deprecated, but still uses --> G
    end

    style D fill:#f9f,stroke:#333,stroke-width:2px
    style G fill:#f9f,stroke:#333,stroke-width:2px

SkillRegistry (The Future)

The SkillRegistry (src/skills/skill-registry.js) is designed to be the central, unified manager for all skills. It handles the lifecycle of skills, from discovery to content retrieval.

SkillLoader (The Current Workhorse - Deprecated)

The SkillLoader (src/skills/skill-loader.js) is currently responsible for discovering and loading skills from local directories (global, project, team, agent-specific). It handles the layering logic, where skills from higher-priority sources override those from lower-priority ones.

SkillManager (The Legacy Matcher - Deprecated)

The SkillManager (src/skills/skill-manager.js) is the runtime component responsible for matching user input to relevant skills and activating them. It also provides the prompt enhancement that gets injected into the AI's system prompt.

SkillsHub (The Remote Gateway)

The SkillsHub (src/skills/hub.js) manages interaction with a remote skill registry, allowing for discovery, installation, and updates of skills from a central repository.

Eligibility Module (src/skills/eligibility.js)

This module provides a set of utility functions to check system prerequisites for skills.

Legacy Adapters (src/skills/adapters/legacy-skill-adapter.js)

This module facilitates the conversion between the old JSON-based skill format and the new UnifiedSkill format.

Bundled Skills Validation (tests/skills/bundled-skills.test.ts)

While a test file, it highlights a critical aspect of the skill system: the integrity of pre-packaged skills.

Starter Packs Module (src/skills/starter-packs.js)

This module provides helpers for working with "starter pack" skills.

Skill Lifecycle Flow

  1. Definition: A skill is created as a SKILL.md file with YAML frontmatter and Markdown content.
  2. Discovery:

  1. Loading & Parsing:

  1. Layering: If multiple skills with the same name are found across different sources, the one from the highest-priority source overrides others.
  2. Eligibility Check: Before a skill can be activated or recommended, the Eligibility Module can verify if its requires prerequisites are met on the current system.
  3. Matching: When a user provides input, SkillManager (or a future agent orchestration layer) uses the skill's triggers and priority to find the most relevant skills.
  4. Activation: The selected skill is activated (either manually or automatically).
  5. Prompt Enhancement: The active skill's systemPrompt and other context are formatted by SkillManager.getSkillPromptEnhancement() and injected into the AI's overall system prompt, guiding its behavior.
  6. Tool Usage: If the skill defines tools, these become available for the AI to invoke.

Contributing to Skills