Skills Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Skills Engine is a core component of the plugsuits project responsible for the discovery, loading, and metadata management of specialized "skills." These skills provide the agent with detailed instructions, workflows, and tool-use patterns for specific tasks, such as version control management or project-specific coding standards.
The engine operates by scanning multiple directories—including bundled assets, global user configurations, and project-local directories—to aggregate a library of actionable knowledge. It supports multiple formats, including legacy single-file Markdown documents and "v2" directory-based skills that can contain supporting scripts and assets.
Sources: packages/harness/src/skills.ts:321-365, packages/harness/README.md:105-115, AGENTS.md:55-58
Architecture and Discovery Logic
The SkillsEngine class serves as the central orchestrator for skill lifecycle management. It utilizes a hierarchical discovery process that allows project-specific skills to override global or bundled ones, ensuring that the agent can be customized for specific environments without losing access to core capabilities.
Discovery Sources
The engine searches up to five distinct directory types defined in the SkillsConfig:
- Bundled: Skills shipped directly with the agent package.
- Global Skills: User-level skills (e.g., located in
~/.claude/skills). - Project Skills: Repository-level skills (e.g., located in
.claude/skills). - Global Commands: Slash commands available globally.
- Project Commands: Slash commands specific to the current working directory.
Sources: packages/harness/src/skills.ts:32-40, packages/cea/src/context/skills.ts:10-16
Discovery Flow
The following diagram illustrates how the SkillsEngine aggregates skills from various sources into a unified map.
The engine uses a priority-based resolution where Project-level skills have the highest precedence (Priority 5), followed by Global (Priority 4) and Bundled (Priority 3).
Sources: packages/harness/src/skills.ts:321-365, packages/harness/src/skills.ts:439-448
Skill Formats
The engine supports three distinct formats, allowing for both simple documentation and complex, multi-file capabilities.
| Format | Description | Key Indicators |
|---|---|---|
| Legacy | Single Markdown files containing YAML-like frontmatter. | *.md files in a flat directory. |
| v2 | Directory-based skills allowing for sub-files and assets. | Directory containing a SKILL.md file. |
| Command | Specialized skills exposed as slash commands (e.g., /git-workflow). | Found in commands/ directories. |
Sources: packages/harness/src/skills.ts:161-163, packages/harness/src/skills.ts:192-194, packages/harness/src/skills.ts:241-245
V2 Skill Structure
V2 skills allow the agent to load specific sub-files using the load_skill tool by providing a relativePath. This is particularly useful for skills that include setup scripts or reference documentation.
Core Components and Tooling
SkillsEngine Class
The primary interface for skill management in the @ai-sdk-tool/harness package.
loadAllSkills(): Aggregates all discovered skills.loadSkillById(id): Retrieves the content and metadata for a specific skill. It handles "prompts:" prefixes for compatibility.loadSkillsMetadata(): Generates a Markdown summary of all available skills to be injected into the system prompt.
Sources: packages/harness/src/skills.ts:321-417
load_skill Tool
A tool implemented in the cea package that allows the LLM to dynamically load skill content into its context during a session.
Implementation Details
Data Structures
The SkillInfo interface defines the metadata tracked for every skill:
export interface SkillInfo {
id: string;
name: string;
description: string;
path: string;
format: "legacy" | "v2" | "command";
source: "bundled" | "global" | "project" | "global-command" | "project-command";
dirPath?: string;
version?: string;
argumentHint?: string;
}
Sources: packages/harness/src/skills.ts:13-25
Security and Validation
The engine enforces several safety checks during skill loading:
- Path Traversal Protection:
load_skillvalidates thatrelativePathdoes not contain..and resolves within the skill directory. - Skill Name Validation: Only alphanumeric characters and hyphens are allowed in skill IDs to prevent command injection or unauthorized file access.
Sources: packages/cea/src/tools/planning/load-skill.ts:33-48, packages/harness/src/skills.ts:130-142
Summary
The Skills Engine provides a robust framework for extending agent capabilities through structured Markdown documentation and directory-based assets. By supporting hierarchical discovery and multi-format loading, it enables developers to ship core "bundled" workflows while allowing end-users to define "project-local" patterns that perfectly match their specific coding environments.