1. 概述

Skill 本质是封装完整业务能力的目录包，Agent 会根据用户提问自动匹配对应技能，内部可读取参考资料、执行 shell 脚本完成任务。

标准 Skill 目录结构

code-reviewer/
├── SKILL.md           # 核心配置+指令（必填，头部YAML元数据+执行步骤）
├── references/        # 参考文档目录（可选）
│   └── style-guide.md
└── scripts/           # 可执行shell脚本（可选，agent通过execute调用）
    └── run-checks.sh

固定核心文件 SKILL.md 必选，参考文档、执行脚本为可选附属资源。

HarnessAgent 支持从两个地方加载技能：

• 技能市场：Git 仓库、Nacos、MySQL、classpath、自定义后端

• 工作区：

  • workspace/skills/ 下大家共用；
  • <userId>/skills/ 下按用户隔离。

2. 技能市场

技能市场是一套统一远程技能仓库抽象接口，统一名称 SkillRepository，用来从外部集中化存储拉取批量技能包，是团队 / 平台统一管理、分发技能的标准入口。

本地 workspace/skills 属于本地静态目录，而技能市场是远程动态仓库，支持实时更新、集中管控、多实例共享。

注意事项：

• 统一配置入口 .skillRepository() ：支持多数据源注册，后注册仓库优先级高于先注册。
• 子 Agent 自动继承父 Agent 所有技能仓库，无需重复配置。

2.1 Git 远程技能仓库

规则：仓库根目录存在 skills/ 则优先读取，否则读取仓库根目录。

引入依赖：

<!-- 依赖 -->
<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-skill-git-repository</artifactId>
    <version>${agentscope.version}</version>
</dependency>

构建配置：

// 自动轻量化拉取，仅HEAD变更时同步
.skillRepository(new GitSkillRepository("https://github.com/xxx/team-skills.git"))

// 关闭自动同步，手动调用 repo.sync() 更新
new GitSkillRepository(gitUrl, false)

2.2 Nacos 配置中心（动态下发、订阅变更）

适合平台在线更新技能，支持实时推送变更，实例退出需 close 释放订阅。

引入依赖：

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-nacos-skill</artifactId>
    <version>${agentscope.version}</version>
</dependency>

构建配置：

NacosSkillRepository market = new NacosSkillRepository(aiService, "namespace");

HarnessAgent.builder()
        .skillRepository(market)
        .build();

2.3 MySQL 数据库（平台统一管理）

支持读写分离，writeable=true 允许 Agent 自学习生成技能回写库。

引入依赖：

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-skill-mysql-repository</artifactId>
    <version>2.0.0-RC2</version>
</dependency>

构建配置：

MysqlSkillRepository registry = MysqlSkillRepository.builder(dataSource)
        .databaseName("agentscope")
        .skillsTableName("skills")
        .createIfNotExist(true)
        .writeable(true)
        .build();

HarnessAgent.builder()
        .skillRepository(registry)
        .build();

2.4 Classpath 内置技能（打包进Jar）

本地静态技能，随应用包一起发布，读取 resources/skills/ 。

src/main/resources/skills/
└── code-reviewer/
    └── SKILL.md

构建配置：

.skillRepository(new ClasspathSkillRepository("skills"))

2.5 多仓库叠加

配置示例：

HarnessAgent.builder()
        .skillRepository(communityMarket)    // 低优先级
        .skillRepository(internalRegistry)
        .skillRepository(teamGitRepo)        // 高优先级，同名覆盖前面
        .build();

3. 工作区

3.1 项目全局技能目录（优先级最低）

全局公共技能，所有 Agent 共享，目录不存在自动跳过，适合个人本地通用工具技能。

配置方式：projectGlobalSkillsDir(path)

配置示例：

        HarnessAgent agent = HarnessAgent.builder()
                .name("harness-demo")
                .description("HarnessAgent Demo")
                .sysPrompt("你是一个 Java 开发 AI 助手")
                .projectGlobalSkillsDir(workspacePath)

3.2 工作区公共技能

项目内团队共用技能，仅当前 Agent 工作区生效，优先级高于技能市场。无需额外代码注册，放置目录即可自动加载。

存储位置：workspace/skills/

workspace/skills/
└── code-reviewer/
    ├── SKILL.md
    ├── references/
    │   └── style-guide.md
    └── scripts/
        └── run-checks.sh

3.3 用户私有技能（最高优先级）

按用户隔离，仅当前 RuntimeContext.userId 匹配的用户可见，同名技能直接覆盖公共/市场版本，用于用户个性化定制、专属能力。

存储位置：workspace/{userId}/skills/

workspace/
├── skills/code-reviewer/SKILL.md   ← 共用版
└── alice/
    └── skills/
        └── code-reviewer/
            └── SKILL.md            ← 只对 alice 生效，覆盖共用版

用户隔离是逻辑抽象，不受底层文件系统模式影响，三种部署模式自动适配：

1. 本机本地磁盘：物理路径 workspace/alice/skills/
2. 共享远端存储：KV 命名空间隔离 agents/{agentId}/users/alice/skills，多副本同步
3. Docker 沙箱模式：宿主用户目录通过 workspaceProjection 自动注入容器 /workspace

4. 同名覆盖优先级

从低 → 高：

优先级	来源	覆盖规则
1（最低）	项目全局目录 ~/.agentscope/skills	最低，会被所有其他来源覆盖
2	技能市场 skillRepository	后注册仓库覆盖先注册仓库
3	工作区公共 workspace/skills	覆盖全部市场与全局目录
4（最高）	用户私有 {userId}/skills	覆盖全部公共来源，仅对当前用户生效

5. Builder 常用技能配置方法

方法	功能说明
skillRepository(repo)	追加一个技能市场，可多次调用
skillRepositories(list)	一次性替换全部技能仓库
projectGlobalSkillsDir(path)	开启全局本地技能目录
disableDynamicSkills()	关闭每轮推理动态拉取合并技能，仅构建时加载一次

disableDynamicSkills 适用场景：

1. 一次性短期任务，执行完成即销毁进程；
2. 技能仓库网络延迟高，频繁拉取影响响应速度；

默认开启动态合并：每次用户推理前自动同步合并所有来源最新技能。

6. 最佳实践

落地极简口诀：

1. description 写场景，不要只写工具名；
2. 主文档精简，大文档丢 references，脚本进 scripts；
3. 一律用相对路径，杜绝硬编码绝对目录；
4. 通用放 Git 市场，项目规则放 workspace；
5. 用户目录只做个性化覆盖，不做主库；
6. 自学习三步走：先起草 → 再加审核 → 最后自动清理。

6.1 技能描述（description）撰写建议

Agent 在第一轮决策时只会读取 name + description，不会加载完整文档，只有判断场景匹配，才会执行 load_skill_through_path 读取全文。

写作规范：

1. 直接写明用户提问句式、业务场景、触发条件；
2. 不要只写能力名词，要写使用时机；
3. 一条技能只对应一类业务场景，不要把多个能力塞进同一个描述。

反面写法（模糊无效），Agent 无法精准匹配用户问句，大概率不会主动触发：

description: 数据分析工具

正面写法（场景化触发）：

description: 用户需要计算指标统计、生成Excel报表、绘制数据趋势折线图时启用本技能

---

6.2 SKILL.md 正文精简规范

1. 正文严格控制在 2000 tokens 左右，只保留执行步骤；
2. 长篇规则、文档、规范全部移入 references/，由Agent按需自行读取；
3. 可执行代码、Shell 脚本、Python 程序统一放入 scripts/；
4. 主文档只写流程：读取哪个文档 → 执行哪个脚本 → 整理输出结果。

优点：减少上下文占用，推理更快，不容易超出窗口限制。

---

6.3 路径写法硬性规范（跨文件系统兼容关键）

强制规则：只写相对路径，禁止写绝对路径。一旦硬编码绝对路径，技能只能在本机调试运行，一进沙箱环境就找不到文件。

框架会自动注入根路径变量 <files-root>，自动拼接成完整路径：

<files-root>/scripts/run.py

• 本地模式：自动拼接宿主目录
• Docker沙箱模式：自动拼接容器内 /workspace
• 远端共享文件系统：自动拼接KV命名空间

正确（兼容本地、容器、远端 KV 所有模式），相对当前 SKILL.md 文件位置：

scripts/run.py
references/guide.md

错误（沙箱/远程文件系统直接失效）：

/workspace/scripts/run.py
/root/skill/ref.md

---

6.4 四层目录分层治理策略（推荐架构）

层级	存放内容	存储位置
公共通用能力	代码评审、Excel分析、SQL查询、通用工具	Git技能市场（全团队共用，版本统一管理）
项目专属规则	项目RPC规范、模块命名、业务定制校验规则	workspace/skills，跟着项目代码一起版本管理
用户私有层	个人临时脚本、自定义覆盖版本	workspace/{userId}/skills
全局基础库	系统级基础工具	projectGlobalSkillsDir

治理原则：

1. 通用能力上收进技能市场，统一迭代，全集群多实例同步生效；
2. 项目独有业务约束下沉到工作区，跟随代码发布；
3. 用户目录只做覆盖与个性化补充，不作为主力技能仓库；
4. 主力技能必须放在全局可见的层级，避免每个用户各自维护一份副本。

冲突覆盖逻辑（天然分层）：市场公共技能 → 项目工作区技能 → 用户私有技能（同名逐级覆盖）。

---

6.5 自学习闭环上线顺序（循序渐进，避免混乱）

严格按照下面顺序逐步开启，不要一次性全开。

阶段1：基础能力落地（必备前置）

先把人工编写的全套技能稳定运行，业务场景全覆盖。

没有人编写新技能时，直接开启自动整理器 curator 毫无意义。

阶段2：开启技能生成工具

enableSkillManageTool(true)

允许Agent自主起草新技能草稿，自动生成目录、SKILL.md、脚本。
产出物默认写入当前用户私有目录。

阶段3：增加人工审核闸门（promotion gate）

草稿技能不能直接升级为正式技能，必须经过人工审核；
审核通过后，才允许从用户私有目录提升到项目公共目录/技能市场，防止脏数据泛滥。

阶段4：最后开启自动清理 curator

定期扫描长期未被调用的陈旧技能，归档、精简、合并废弃技能，保持技能库整洁。

---