Class ShellSkills

java.lang.Object

dev.langchain4j.skills.shell.ShellSkills

@Experimental
public class ShellSkills
extends Object

Configures and exposes a set of FileSystemSkills to an LLM using shell commands.

WARNING: Shell execution is inherently unsafe. Commands run directly in the host process environment without any sandboxing, containerization, or privilege restriction. A misbehaving or prompt-injected LLM can execute arbitrary commands on the machine running your application. Only use this in controlled environments where you fully trust the input.

This corresponds to the Filesystem-based agents integration approach from the Agent Skills specification.

Only a run_shell_command tool is registered. The LLM reads SKILL.md files and other resources directly via shell commands using the absolute paths provided in the formatAvailableSkills() via <location>.

Typical usage with an AI Service:

ShellSkills skills = ShellSkills.from(FileSystemSkillLoader.loadSkills(skillsDir));

MyAiService service = AiServices.builder(MyAiService.class)
        .chatModel(chatModel)
        .systemMessage("You have access to the following skills:\n" + skills.formatAvailableSkills()
                + "\nWhen the user's request relates to one of these skills, read its SKILL.md before proceeding.")
        .toolProvider(skills.toolProvider())
        .build();

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ShellSkills.Builder

Constructor Summary

Constructors

Constructor	Description
ShellSkills(ShellSkills.Builder builder)

Method Summary

Modifier and Type	Method	Description
static ShellSkills.Builder	builder()
String	formatAvailableSkills()	Returns an XML-formatted string listing all configured skills with their names, descriptions, and absolute file-system paths to their SKILL.md files.
static ShellSkills	from(FileSystemSkill... skills)	Creates a ShellSkills instance with default configuration from the given skills.
static ShellSkills	from(Collection<? extends FileSystemSkill> skills)	Creates a ShellSkills instance with default configuration from the given collection of skills.
ToolProvider	toolProvider()	Returns the ToolProvider that exposes the run_shell_command tool to the LLM.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

ShellSkills

public ShellSkills(ShellSkills.Builder builder)

Method Details

toolProvider

public ToolProvider toolProvider()

Returns the ToolProvider that exposes the run_shell_command tool to the LLM. Pass this to AiServices.builder(...).toolProvider(...).

formatAvailableSkills

public String formatAvailableSkills()

Returns an XML-formatted string listing all configured skills with their names, descriptions, and absolute file-system paths to their SKILL.md files.

Include this in the system message so the LLM knows which skills are available and where to find their instructions via run_shell_command.

Example output:

<available_skills>
<skill>
<name>docx</name>
<description>Edit and review Word documents using tracked changes</description>
<location>/path/to/skills/docx/SKILL.md</location>
</skill>
</available_skills>

from

public static ShellSkills from(Collection<? extends FileSystemSkill> skills)

Creates a ShellSkills instance with default configuration from the given collection of skills.

from

public static ShellSkills from(FileSystemSkill... skills)

Creates a ShellSkills instance with default configuration from the given skills.

builder

public static ShellSkills.Builder builder()