Agent Skills

Overview

Agent Skills are modular skill packages that extend agent capabilities. Each Skill contains instructions, metadata, and optional resources (such as scripts, reference documentation, examples, etc.), which agents will automatically use for relevant tasks.

Reference: Claude Agent Skills Official Documentation

Core Features

Progressive Disclosure Mechanism

Adopts three-stage on-demand loading to optimize context: Initially loads only metadata (~100 tokens/Skill) → AI loads complete instructions when needed (<5k tokens) → On-demand access to resource files. Tools are also progressively disclosed, activated only when the Skill is in use.

Workflow: User Query → AI Identifies Relevant Skill → Calls load_skill_through_path Tool to Load Content and Activate Bound Tools → On-Demand Resource Access → Task Completion

Unified Loading Tool: load_skill_through_path(skillId, resourcePath) provides a single entry point for loading skill resources

  • skillId uses an enum field, ensuring selection only from registered Skills, guaranteeing accuracy

  • resourcePath is the resource path relative to the Skill root directory (e.g., references/api-doc.md)

  • Returns a list of all available resource paths when the path is incorrect, helping the LLM correct errors

Adaptive Design

We have further abstracted skills so that their discovery and content loading are no longer dependent on the file system. Instead, the LLM discovers and loads skill content and resources through tools. At the same time, to maintain compatibility with the existing skill ecosystem and resources, skills are still organized according to file system structure for their content and resources.

Organize your skill content and resources just like organizing a skill directory in a file system!

Taking the Skill Structure as an example, this directory-structured skill is represented in our system as:

AgentSkill skill = AgentSkill.builder()
    .name("data_analysis")
    .description("Use this skill when analyzing data, calculating statistics, or generating reports")
    .skillContent("# Data Analysis\n...")
    .addResource("references/api-doc.md", "# API Reference\n...")
    .addResource("references/best-practices.md", "# Best Practices\n...")
    .addResource("examples/example1.java", "public class Example1 {\n...\n}")
    .addResource("scripts/process.py", "def process(data): ...\n")
    .build();

Skill Structure

skill-name/
├── SKILL.md          # Required: Entry file with YAML frontmatter and instructions
├── references/       # Optional: Detailed reference documentation
│   ├── api-doc.md
│   └── best-practices.md
├── examples/         # Optional: Working examples
│   └── example1.java
└── scripts/          # Optional: Executable scripts
    └── process.py

SKILL.md Format Specification

---
name: skill-name                    # Required: Skill name (lowercase letters, numbers, underscores)
description: This skill should be used when...  # Required: Trigger description, explaining when to use
homepage: https://example.com/docs  # Optional: Additional metadata exposed to the agent prompt
metadata:
  clawdbot:
    requires:
      env:
        - API_KEY
---

# Skill Name

## Feature Overview
[Detailed description of the skill's functionality]

## Usage Instructions
[Usage steps and best practices]

## Available Resources
- references/api-doc.md: API reference documentation
- scripts/process.py: Data processing script

Required Fields:

  • name - Skill name (lowercase letters, numbers, underscores)

  • description - Skill functionality and usage scenarios, helps AI determine when to use

Metadata Notes:

  • Any additional YAML frontmatter fields are preserved as skill metadata, not limited to predefined fields

  • Nested maps and lists are supported and keep their structure and insertion order

  • Frontmatter is parsed with SnakeYAML SafeConstructor; only top-level YAML objects of type Map are accepted

  • Invalid frontmatter or frontmatter exceeding the parser limit is ignored and treated as empty metadata

Quick Start

1. Create a Skill

Method 1: Using Builder

AgentSkill skill = AgentSkill.builder()
    .name("data_analysis")
    .description("Use when analyzing data...")
    .putMetadata("homepage", "https://example.com/docs")
    .skillContent("# Data Analysis\n...")
    .addResource("references/formulas.md", "# Common Formulas\n...")
    .source("custom")
    .build();

Method 2: Create from Markdown

// Prepare SKILL.md content
String skillMd = """
---
name: data_analysis
description: Use this skill when analyzing data, calculating statistics, or generating reports
---
# Skill Name
Content...
""";

// Prepare resource files (optional)
Map<String, String> resources = Map.of(
    "references/formulas.md", "# Common Formulas\n...",
    "examples/sample.csv", "name,value\nA,100\nB,200"
);

// Create Skill
AgentSkill skill = SkillUtil.createFrom(skillMd, resources);

Method 3: Direct Construction

AgentSkill skill = new AgentSkill(
    "data_analysis",                    // name
    "Use when analyzing data...",       // description
    "# Data Analysis\n...",             // skillContent
    resources                            // resources (can be null)
);

2. Integrate with ReActAgent

Using SkillBox

Toolkit toolkit = new Toolkit();

SkillBox skillBox = new SkillBox(toolkit);
skillBox.registerSkill(skill1);

ReActAgent agent = ReActAgent.builder()
        .name("DataAnalyst")
        .model(model)
        .toolkit(toolkit)
        .skillBox(skillBox)  // Automatically registers skill tools and hook
        .memory(new InMemoryMemory())
        .build();

3. Use Skills

Simplified Integration

SkillBox skillBox = new SkillBox(new Toolkit());

skillBox.registerSkill(dataSkill);

ReActAgent agent = ReActAgent.builder()
    .name("Assistant")
    .model(model)
    .skillBox(skillBox)
    .build();

Advanced Features

Feature 1: Progressive Disclosure of Tools

Bind Tools to Skills for on-demand activation. Avoids context pollution from pre-registering all Tools, only passing relevant Tools to LLM when the Skill is actively used.

Lifecycle of Progressively Disclosed Tools: Tool lifecycle remains consistent with Skill lifecycle. Once a Skill is activated, Tools remain available throughout the entire session, avoiding the call failures caused by Tool deactivation after each conversation round in the old mechanism.

Example Code:

Toolkit toolkit = new Toolkit();
SkillBox skillBox = new SkillBox(toolkit);

AgentSkill dataSkill = AgentSkill.builder()
    .name("data_analysis")
    .description("Comprehensive data analysis capabilities")
    .skillContent("# Data Analysis\n...")
    .build();

AgentTool loadDataTool = new AgentTool(...);

skillBox.registration()
    .skill(dataSkill)
    .tool(loadDataTool)
    .apply();

ReActAgent agent = ReActAgent.builder()
    .name("Assistant")
    .model(model)
    .toolkit(toolkit)
    .skillBox(skillBox)
    .build();

Feature 2: Code Execution Capabilities

Provides an isolated code execution environment for Skills, supporting Shell commands, file read/write operations, etc. Uses Builder pattern to compose tools and configuration on demand.

Basic Usage:

SkillBox skillBox = new SkillBox(toolkit);

// Enable all code execution tools (Shell, read file, write file)
skillBox.codeExecution()
    .withShell()
    .withRead()
    .withWrite()
    .enable();

Configuration Reference:

  • Tool Selection: Combine withShell(), withRead(), withWrite() as needed — only explicitly enabled tools are registered

  • workDir: Shared working directory for all tools. Created automatically when specified; if omitted, a temporary directory agentscope-code-execution-* is created lazily and cleaned up on JVM exit

  • uploadDir: Upload location for Skill resource files; defaults to workDir/skills

  • File Filtering: Controls which resource files are allowed to upload. Defaults to scripts/, assets/ folders and .py, .js, .sh extensions. Adjust with includeFolders()/includeExtensions(), or fully customize with fileFilter() (the two approaches are mutually exclusive)

  • Custom Shell: withShell(customShellTool) accepts a custom tool whose baseDir is automatically overridden with workDir while preserving its security policy

Custom Configuration:

// Specify directory + custom Shell + file filtering
ShellCommandTool customShell = new ShellCommandTool(
    null,  // baseDir will be automatically overridden with workDir
    Set.of("python3", "node", "npm"),
    command -> askUserApproval(command)
);

skillBox.codeExecution()
    .workDir("/data/agent-workspace")              // working directory
    .uploadDir("/data/agent-workspace/my-skills")  // optional, defaults to workDir/skills
    .includeFolders(Set.of("scripts/", "data/"))   // optional, customize upload folders
    .includeExtensions(Set.of(".py", ".json"))      // optional, customize upload extensions
    .withShell(customShell)
    .withRead()
    .withWrite()
    .enable();

// Or use a fully custom file filter (mutually exclusive with includeFolders/includeExtensions)
skillBox.codeExecution()
    .fileFilter(path -> path.endsWith(".py"))  // or SkillFileFilter.acceptAll()
    .withRead()
    .withWrite()
    .enable();

Feature 3: Skill Persistence Storage

Why is this feature needed?

Skills need to remain available after application restart, or be shared across different environments. Persistence storage supports:

File System Storage

AgentSkillRepository repo = new FileSystemSkillRepository(Path.of("./skills"));
repo.save(List.of(skill), false);
AgentSkill loaded = repo.getSkill("data_analysis");

MySQL Database Storage

// Using simple constructor with default database/table names
DataSource dataSource = createDataSource();
MysqlSkillRepository repo = new MysqlSkillRepository(dataSource, true, true);

// Using Builder for custom configuration
MysqlSkillRepository repo = MysqlSkillRepository.builder(dataSource)
        .databaseName("my_database")
        .skillsTableName("my_skills")
        .resourcesTableName("my_resources")
        .createIfNotExist(true)
        .writeable(true)
        .build();

repo.save(List.of(skill), false);
AgentSkill loaded = repo.getSkill("data_analysis");

Git Repository (Read-Only)

Used to load Skills from a Git repository (read-only). Supports HTTPS and SSH.

Update mechanism

  • By default, each read triggers a lightweight remote reference check; a pull runs only when the remote HEAD changes.

  • You can disable auto-sync via the constructor and call sync() manually when you want to refresh.

AgentSkillRepository repo = new GitSkillRepository(
    "https://github.com/your-org/your-skills-repo.git");
AgentSkill skill = repo.getSkill("data-analysis");
List<AgentSkill> allSkills = repo.getAllSkills();

GitSkillRepository manualRepo = new GitSkillRepository(
    "https://github.com/your-org/your-skills-repo.git", false);
manualRepo.sync();

If the repository contains a skills/ subdirectory, it will be used; otherwise the repo root is used.

Classpath Repository (Read-Only)

Used to load pre-packaged Skills from classpath resources. Automatically compatible with standard JARs and Spring Boot Fat JARs.

try (ClasspathSkillRepository repository = new ClasspathSkillRepository("skills")) {
    AgentSkill skill = repository.getSkill("data-analysis");
    List<AgentSkill> allSkills = repository.getAllSkills();
} catch //...

Resource structure: Place multiple skill subdirectories under src/main/resources/skills/, each containing a SKILL.md.

Note: JarSkillRepositoryAdapter is deprecated. Use ClasspathSkillRepository instead.

Nacos Repository (Read-Only)

Pulls or subscribes to Skills from Nacos via a pre-built AiService (or Nacos connection config). The Agent fetches Skills from Nacos at runtime in real time, with support for change subscription and automatic awareness. Suitable for online scenarios that need to stay in sync with Nacos.

// Create Nacos skill repository with a pre-built AiService
try (NacosSkillRepository repository = new NacosSkillRepository(aiService, "namespace")) {
    AgentSkill skill = repository.getSkill("data-analysis");
    boolean exists = repository.skillExists("data-analysis");
} catch //...

Note: Add the agentscope-extensions-nacos-skill dependency.

Feature 4: Custom Skill Prompts

When SkillBox injects a system prompt into the Agent, it generates one XML <skill> entry per registered Skill so the LLM can decide when to load which Skill. Metadata is rendered directly from AgentSkill.getMetadata(), and <skill-id> is always appended for tool loading.

  • instruction: The prompt header, explaining how to use Skills (how to load them, path conventions, etc.). Defaults to a built-in load_skill_through_path usage guide

  • XML metadata rendering: Scalar metadata becomes a child element, nested maps become nested XML, and lists become repeated <item> elements

  • Metadata exposure control: skillBox.setExposeAllSkillMetadata(false) limits the prompt to name, description, and skill-id; the default is to expose all metadata fields

When code execution is enabled, the section appended after </available_skills> can also be customized via .codeExecutionInstruction():

  • codeExecutionInstruction: Template for the code execution section; every %s placeholder will be replaced with the uploadDir absolute path. Passing null or blank uses the built-in default.

Passing null or a blank string for instruction or codeExecutionInstruction uses the built-in default.

Example:

// Customize the instruction header
String customInstruction = """
    ## Available Skills
    When a task matches a skill, load it with load_skill_through_path.
    """;

SkillBox skillBox = new SkillBox(toolkit, customInstruction);

// Optionally expose only core metadata fields in the prompt
skillBox.setExposeAllSkillMetadata(false);

// Customize the code execution section (takes effect when code execution is enabled)
skillBox.codeExecution()
    .workDir("/data/workspace")
    .codeExecutionInstruction("""
        ## Script Execution
        Skills root directory: %s
        Always use absolute paths when running scripts.
        """)
    .withShell()
    .enable();

Performance Optimization Recommendations

  1. Control SKILL.md Size: Keep under 5k tokens, recommended 1.5-2k tokens

  2. Organize Resources Properly: Place detailed documentation in references/ rather than SKILL.md

  3. Regularly Clean Versions: Use clearSkillOldVersions() to clean up old versions no longer needed

  4. Avoid Duplicate Registration: Leverage duplicate registration protection mechanism; same Skill object with multiple Tools won’t create duplicate versions