Skip to content

Commit 0ce4ea5

Browse files
AlbumenJAlbumenJ
committed
deploy: 8074f91 
1 parent 06fe079 commit 0ce4ea5

File tree

7 files changed

+286
-20
lines changed

7 files changed

+286
-20
lines changed

‎_sources/en/task/agent-skill.md‎

Lines changed: 55 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,11 @@ Adopts **three-stage on-demand loading** to optimize context: Initially loads on
1414

1515
**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
1616

17+
**Unified Loading Tool**: `load_skill_through_path(skillId, resourcePath)` provides a single entry point for loading skill resources
18+
- `skillId` uses an enum field, ensuring selection only from registered Skills, guaranteeing accuracy
19+
- `resourcePath` is the resource path relative to the Skill root directory (e.g., `references/api-doc.md`)
20+
- Returns a list of all available resource paths when the path is incorrect, helping the LLM correct errors
21+
1722
### Adaptive Design
1823

1924
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.
@@ -165,6 +170,8 @@ ReActAgent agent = ReActAgent.builder()
165170

166171
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.
167172

173+
**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.
174+
168175
**Example Code**:
169176

170177
```java
@@ -192,7 +199,54 @@ ReActAgent agent = ReActAgent.builder()
192199
.build();
193200
```
194201

195-
### Feature 2: Skill Persistence Storage
202+
### Feature 2: Code Execution Capabilities
203+
204+
Provides an isolated code execution folder for Skills, supporting Shell commands, file read/write operations, etc. Uses Builder pattern for flexible configuration of required tools.
205+
206+
**Basic Usage**:
207+
208+
```java
209+
SkillBox skillBox = new SkillBox(toolkit);
210+
211+
// Enable all code execution tools (Shell, read file, write file)
212+
skillBox.codeExecution()
213+
.withShell()
214+
.withRead()
215+
.withWrite()
216+
.enable();
217+
```
218+
219+
**Custom Configuration**:
220+
221+
```java
222+
// Customize working directory and Shell command whitelist
223+
ShellCommandTool customShell = new ShellCommandTool(
224+
null, // baseDir will be automatically set to workDir
225+
Set.of("python3", "node", "npm"),
226+
command -> askUserApproval(command) // Optional command approval callback
227+
);
228+
229+
skillBox.codeExecution()
230+
.workDir("/path/to/workdir") // Specify working directory
231+
.withShell(customShell) // Use custom Shell tool
232+
.withRead() // Enable file reading
233+
.withWrite() // Enable file writing
234+
.enable();
235+
236+
// Or enable only file operations, without Shell
237+
skillBox.codeExecution()
238+
.withRead()
239+
.withWrite()
240+
.enable();
241+
```
242+
243+
**Core Features**:
244+
- **Unified Working Directory**: All tools share the same `workDir`, ensuring file isolation
245+
- **Selective Enabling**: Flexibly combine Shell, read file, and write file tools as needed
246+
- **Flexible Configuration**: Supports custom ShellCommandTool to meet customization requirements
247+
- **Automatic Management**: Automatically creates temporary directory when `workDir` is not specified, with automatic cleanup on program exit
248+
249+
### Feature 3: Skill Persistence Storage
196250

197251
**Why is this feature needed?**
198252

‎_sources/zh/task/agent-skill.md‎

Lines changed: 55 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,11 @@ Agent Skill 是扩展智能体能力的模块化技能包。每个 Skill 包含
1414

1515
**工作流程:** 用户提问 → AI 识别相关 Skill → 调用 `load_skill_through_path` 工具加载内容并激活绑定的 Tool → 按需访问资源 → 完成任务
1616

17+
**统一加载工具**: `load_skill_through_path(skillId, resourcePath)` 提供单一入口加载技能资源
18+
- `skillId` 使用枚举字段, 确保只能从已注册的 Skill 中选择, 保证准确性
19+
- `resourcePath` 是相对于 Skill 根目录的资源路径(如 `references/api-doc.md`)
20+
- 路径错误时会返回所有可用的资源路径列表,帮助 LLM 纠正
21+
1722
### 适应性设计
1823

1924
我们将 Skill 进行了进一步的抽象,使其的发现和内容加载不再依赖于文件系统,而是 LLM 通过 Tool 来发现和加载 Skill 的内容和资源。同时为了兼容已有的 Skill 生态与资源,Skill 的组织形式依旧按照文件系统的结构来组织它的内容和资源。
@@ -162,6 +167,8 @@ ReActAgent agent = ReActAgent.builder()
162167

163168
将 Tool 与 Skill 绑定,实现按需激活。避免预先注册所有 Tool 导致的上下文污染,仅在 Skill 被 LLM 使用时才传递相关 Tool。
164169

170+
**渐进式暴露的Tool的生命周期**: Tool 与 Skill 生命周期保持一致, Skill 激活后 Tool 在整个会话期间保持可用, 避免了旧机制中每轮对话后 Tool 失活导致的调用失败问题。
171+
165172
**示例代码**:
166173

167174
```java
@@ -189,7 +196,54 @@ ReActAgent agent = ReActAgent.builder()
189196
.build();
190197
```
191198

192-
### 功能 2: Skill 持久化存储
199+
### 功能 2: 代码执行能力
200+
201+
为 Skill 提供隔离的代码执行文件夹,支持 Shell 命令、文件读写等操作。使用 Builder 模式灵活配置所需工具。
202+
203+
**基础用法**:
204+
205+
```java
206+
SkillBox skillBox = new SkillBox(toolkit);
207+
208+
// 启用所有代码执行工具(Shell、读文件、写文件)
209+
skillBox.codeExecution()
210+
.withShell()
211+
.withRead()
212+
.withWrite()
213+
.enable();
214+
```
215+
216+
**自定义配置**:
217+
218+
```java
219+
// 自定义工作目录和 Shell 命令白名单
220+
ShellCommandTool customShell = new ShellCommandTool(
221+
null, // baseDir 会被自动设置为 workDir
222+
Set.of("python3", "node", "npm"),
223+
command -> askUserApproval(command) // 可选的命令审批回调
224+
);
225+
226+
skillBox.codeExecution()
227+
.workDir("/path/to/workdir") // 指定工作目录
228+
.withShell(customShell) // 使用自定义 Shell 工具
229+
.withRead() // 启用文件读取
230+
.withWrite() // 启用文件写入
231+
.enable();
232+
233+
// 或仅启用文件操作,不启用 Shell
234+
skillBox.codeExecution()
235+
.withRead()
236+
.withWrite()
237+
.enable();
238+
```
239+
240+
**核心特性**:
241+
- **统一工作目录**: 所有工具共享同一 `workDir`,确保文件隔离
242+
- **选择性启用**: 根据需求灵活组合 Shell、读文件、写文件工具
243+
- **灵活配置**: 支持自定义 ShellCommandTool, 满足定制化的ShellCommandTool需求
244+
- **自动管理**: 未指定 `workDir` 时自动创建临时目录,程序退出时自动清理
245+
246+
### 功能 3: Skill 持久化存储
193247

194248
**为什么需要这个功能?**
195249

‎en/task/agent-skill.html‎

Lines changed: 57 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
<meta name="viewport" content="width=device-width,initial-scale=1">
55
<meta name="color-scheme" content="light dark"><meta name="viewport" content="width=device-width, initial-scale=1" />
66

7-
<meta property="article:modified_time" content="2026-01-14T03:13:39+00:00" /><link rel="index" title="Index" href="../../genindex.html"><link rel="search" title="Search" href="../../search.html"><link rel="next" title="RAG (Retrieval-Augmented Generation)" href="rag.html"><link rel="prev" title="MCP (Model Context Protocol)" href="mcp.html">
7+
<meta property="article:modified_time" content="2026-01-23T08:20:39+00:00" /><link rel="index" title="Index" href="../../genindex.html"><link rel="search" title="Search" href="../../search.html"><link rel="next" title="RAG (Retrieval-Augmented Generation)" href="rag.html"><link rel="prev" title="MCP (Model Context Protocol)" href="mcp.html">
88
<link rel="canonical" href="https://java.agentscope.io/en/task/agent-skill.html">
99
<link rel="prefetch" href="../../_static/logo.svg" as="image">
1010

@@ -433,6 +433,12 @@ <h2>Core Features<a class="headerlink" href="#core-features" title="Link to this
433433
<h3>Progressive Disclosure Mechanism<a class="headerlink" href="#progressive-disclosure-mechanism" title="Link to this heading"></a></h3>
434434
<p>Adopts <strong>three-stage on-demand loading</strong> to optimize context: Initially loads only metadata (~100 tokens/Skill) → AI loads complete instructions when needed (&lt;5k tokens) → On-demand access to resource files. Tools are also progressively disclosed, activated only when the Skill is in use.</p>
435435
<p><strong>Workflow:</strong> User Query → AI Identifies Relevant Skill → Calls <code class="docutils literal notranslate"><span class="pre">load_skill_through_path</span></code> Tool to Load Content and Activate Bound Tools → On-Demand Resource Access → Task Completion</p>
436+
<p><strong>Unified Loading Tool</strong>: <code class="docutils literal notranslate"><span class="pre">load_skill_through_path(skillId,</span> <span class="pre">resourcePath)</span></code> provides a single entry point for loading skill resources</p>
437+
<ul class="simple">
438+
<li><p><code class="docutils literal notranslate"><span class="pre">skillId</span></code> uses an enum field, ensuring selection only from registered Skills, guaranteeing accuracy</p></li>
439+
<li><p><code class="docutils literal notranslate"><span class="pre">resourcePath</span></code> is the resource path relative to the Skill root directory (e.g., <code class="docutils literal notranslate"><span class="pre">references/api-doc.md</span></code>)</p></li>
440+
<li><p>Returns a list of all available resource paths when the path is incorrect, helping the LLM correct errors</p></li>
441+
</ul>
436442
</section>
437443
<section id="adaptive-design">
438444
<h3>Adaptive Design<a class="headerlink" href="#adaptive-design" title="Link to this heading"></a></h3>
@@ -586,6 +592,7 @@ <h2>Advanced Features<a class="headerlink" href="#advanced-features" title="Link
586592
<section id="feature-1-progressive-disclosure-of-tools">
587593
<h3>Feature 1: Progressive Disclosure of Tools<a class="headerlink" href="#feature-1-progressive-disclosure-of-tools" title="Link to this heading"></a></h3>
588594
<p>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.</p>
595+
<p><strong>Lifecycle of Progressively Disclosed Tools</strong>: 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.</p>
589596
<p><strong>Example Code</strong>:</p>
590597
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="n">Toolkit</span><span class="w"> </span><span class="n">toolkit</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">Toolkit</span><span class="p">();</span>
591598
<span class="n">SkillBox</span><span class="w"> </span><span class="n">skillBox</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">SkillBox</span><span class="p">(</span><span class="n">toolkit</span><span class="p">);</span>
@@ -612,8 +619,52 @@ <h3>Feature 1: Progressive Disclosure of Tools<a class="headerlink" href="#featu
612619
</pre></div>
613620
</div>
614621
</section>
615-
<section id="feature-2-skill-persistence-storage">
616-
<h3>Feature 2: Skill Persistence Storage<a class="headerlink" href="#feature-2-skill-persistence-storage" title="Link to this heading"></a></h3>
622+
<section id="feature-2-code-execution-capabilities">
623+
<h3>Feature 2: Code Execution Capabilities<a class="headerlink" href="#feature-2-code-execution-capabilities" title="Link to this heading"></a></h3>
624+
<p>Provides an isolated code execution folder for Skills, supporting Shell commands, file read/write operations, etc. Uses Builder pattern for flexible configuration of required tools.</p>
625+
<p><strong>Basic Usage</strong>:</p>
626+
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="n">SkillBox</span><span class="w"> </span><span class="n">skillBox</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">SkillBox</span><span class="p">(</span><span class="n">toolkit</span><span class="p">);</span>
627+
628+
<span class="c1">// Enable all code execution tools (Shell, read file, write file)</span>
629+
<span class="n">skillBox</span><span class="p">.</span><span class="na">codeExecution</span><span class="p">()</span>
630+
<span class="w"> </span><span class="p">.</span><span class="na">withShell</span><span class="p">()</span>
631+
<span class="w"> </span><span class="p">.</span><span class="na">withRead</span><span class="p">()</span>
632+
<span class="w"> </span><span class="p">.</span><span class="na">withWrite</span><span class="p">()</span>
633+
<span class="w"> </span><span class="p">.</span><span class="na">enable</span><span class="p">();</span>
634+
</pre></div>
635+
</div>
636+
<p><strong>Custom Configuration</strong>:</p>
637+
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="c1">// Customize working directory and Shell command whitelist</span>
638+
<span class="n">ShellCommandTool</span><span class="w"> </span><span class="n">customShell</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="k">new</span><span class="w"> </span><span class="n">ShellCommandTool</span><span class="p">(</span>
639+
<span class="w"> </span><span class="kc">null</span><span class="p">,</span><span class="w"> </span><span class="c1">// baseDir will be automatically set to workDir</span>
640+
<span class="w"> </span><span class="n">Set</span><span class="p">.</span><span class="na">of</span><span class="p">(</span><span class="s">&quot;python3&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;node&quot;</span><span class="p">,</span><span class="w"> </span><span class="s">&quot;npm&quot;</span><span class="p">),</span>
641+
<span class="w"> </span><span class="n">command</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">askUserApproval</span><span class="p">(</span><span class="n">command</span><span class="p">)</span><span class="w"> </span><span class="c1">// Optional command approval callback</span>
642+
<span class="p">);</span>
643+
644+
<span class="n">skillBox</span><span class="p">.</span><span class="na">codeExecution</span><span class="p">()</span>
645+
<span class="w"> </span><span class="p">.</span><span class="na">workDir</span><span class="p">(</span><span class="s">&quot;/path/to/workdir&quot;</span><span class="p">)</span><span class="w"> </span><span class="c1">// Specify working directory</span>
646+
<span class="w"> </span><span class="p">.</span><span class="na">withShell</span><span class="p">(</span><span class="n">customShell</span><span class="p">)</span><span class="w"> </span><span class="c1">// Use custom Shell tool</span>
647+
<span class="w"> </span><span class="p">.</span><span class="na">withRead</span><span class="p">()</span><span class="w"> </span><span class="c1">// Enable file reading</span>
648+
<span class="w"> </span><span class="p">.</span><span class="na">withWrite</span><span class="p">()</span><span class="w"> </span><span class="c1">// Enable file writing</span>
649+
<span class="w"> </span><span class="p">.</span><span class="na">enable</span><span class="p">();</span>
650+
651+
<span class="c1">// Or enable only file operations, without Shell</span>
652+
<span class="n">skillBox</span><span class="p">.</span><span class="na">codeExecution</span><span class="p">()</span>
653+
<span class="w"> </span><span class="p">.</span><span class="na">withRead</span><span class="p">()</span>
654+
<span class="w"> </span><span class="p">.</span><span class="na">withWrite</span><span class="p">()</span>
655+
<span class="w"> </span><span class="p">.</span><span class="na">enable</span><span class="p">();</span>
656+
</pre></div>
657+
</div>
658+
<p><strong>Core Features</strong>:</p>
659+
<ul class="simple">
660+
<li><p><strong>Unified Working Directory</strong>: All tools share the same <code class="docutils literal notranslate"><span class="pre">workDir</span></code>, ensuring file isolation</p></li>
661+
<li><p><strong>Selective Enabling</strong>: Flexibly combine Shell, read file, and write file tools as needed</p></li>
662+
<li><p><strong>Flexible Configuration</strong>: Supports custom ShellCommandTool to meet customization requirements</p></li>
663+
<li><p><strong>Automatic Management</strong>: Automatically creates temporary directory when <code class="docutils literal notranslate"><span class="pre">workDir</span></code> is not specified, with automatic cleanup on program exit</p></li>
664+
</ul>
665+
</section>
666+
<section id="feature-3-skill-persistence-storage">
667+
<h3>Feature 3: Skill Persistence Storage<a class="headerlink" href="#feature-3-skill-persistence-storage" title="Link to this heading"></a></h3>
617668
<p><strong>Why is this feature needed?</strong></p>
618669
<p>Skills need to remain available after application restart, or be shared across different environments. Persistence storage supports:</p>
619670
<ul class="simple">
@@ -703,7 +754,7 @@ <h2>Related Documentation<a class="headerlink" href="#related-documentation" tit
703754
Made with
704755
<a href="https://github.com/pradyunsg/furo">Furo</a>
705756
<div class="last-updated">
706-
Last updated on 2026-01-14</div>
757+
Last updated on 2026-01-23</div>
707758
</div>
708759
<div class="right-details">
709760
<div class="icons">
@@ -764,7 +815,8 @@ <h2>Related Documentation<a class="headerlink" href="#related-documentation" tit
764815
<li><a class="reference internal" href="#simplified-integration">Simplified Integration</a></li>
765816
<li><a class="reference internal" href="#advanced-features">Advanced Features</a><ul>
766817
<li><a class="reference internal" href="#feature-1-progressive-disclosure-of-tools">Feature 1: Progressive Disclosure of Tools</a></li>
767-
<li><a class="reference internal" href="#feature-2-skill-persistence-storage">Feature 2: Skill Persistence Storage</a></li>
818+
<li><a class="reference internal" href="#feature-2-code-execution-capabilities">Feature 2: Code Execution Capabilities</a></li>
819+
<li><a class="reference internal" href="#feature-3-skill-persistence-storage">Feature 3: Skill Persistence Storage</a></li>
768820
<li><a class="reference internal" href="#performance-optimization-recommendations">Performance Optimization Recommendations</a></li>
769821
</ul>
770822
</li>

0 commit comments

Comments
 (0)