zclaw_openfang/docs/features/04-skills-ecosystem/00-skill-system.md

Skills 系统概述 (Skill System)

分类: Skills 生态 优先级: P1 - 重要 成熟度: L4 - 生产 最后更新: 2026-03-24

✅ 实现更新: Skills 动态扫描已实现。Kernel 集成了 SkillRegistry，支持通过 Tauri 命令 skill_list 和 skill_refresh 动态发现所有 69 个技能。新增 execute_skill 工具，允许 Agent 在对话中直接调用技能。

---

一、功能概述

1.1 基本信息

Skills 系统是 ZCLAW 的核心扩展机制，通过 SKILL.md 文件定义 Agent 的专业技能，支持自动发现和推荐。

属性	值
分类	Skills 生态
优先级	P1
成熟度	L4
依赖	SkillRegistry (Rust), SkillDiscoveryEngine (TypeScript)
SKILL.md 文件	69
动态发现技能	69 (100%)
execute_skill 工具	✅ 已实现

1.2 动态扫描实现

架构变更 (2026-03-24):

• Kernel 结构体添加 skills: Arc<SkillRegistry> 字段
• KernelConfig 添加 skills_dir: Option<PathBuf> 配置
• 新增 Tauri 命令 skill_list 和 skill_refresh
• 前端 SkillDiscoveryEngine 从后端动态加载技能

数据流:

kernel_init()
    → SkillRegistry::new()
    → SkillRegistry::add_skill_dir("skills/")
    → discover_skills() 扫描 SKILL.md
    → 前端调用 skill_list 获取技能

1.3 相关文件

文件	路径	用途
技能目录	skills/	69 个 SKILL.md
Rust 注册中心	crates/zclaw-skills/src/registry.rs	技能注册和发现
Rust 加载器	crates/zclaw-skills/src/loader.rs	SKILL.md 解析
Kernel 集成	crates/zclaw-kernel/src/kernel.rs	Kernel 集成 SkillRegistry
Tauri 命令	desktop/src-tauri/src/kernel_commands.rs	skill_list, skill_refresh
前端发现引擎	desktop/src/lib/skill-discovery.ts	从后端加载技能
模板	skills/.templates/skill-template.md	技能模板
协调规则	skills/.coordination/	协作规则

---

二、设计初衷

2.1 问题背景

用户痛点:

1. 单一 Agent 能力有限
2. 不同任务需要不同专业技能
3. 技能定义缺乏标准

系统缺失能力:

• 缺乏标准化的技能定义
• 缺乏技能发现机制
• 缺乏多技能协作

为什么需要: 标准化的技能系统让 Agent 可以动态获得专业能力，支持多 Agent 协作。

2.2 设计目标

1. 标准化: SKILL.md 统一格式
2. 可发现: 自动发现和推荐技能
3. 可组合: 多技能协作
4. 可扩展: 易于添加新技能

2.3 SKILL.md 格式

---
name: skill-name
description: "简短描述"
triggers:
  - "触发词1"
  - "触发词2"
tools:
  - bash
  - read
  - write
---

## Identity & Memory
[角色定义、性格、专业技能]

## Core Mission
[负责与不负责的边界]

## Core Capabilities
[具体能力描述]

## Workflow Process
[标准化工作流程]

## Deliverable Format
[交付物格式]

## Collaboration Triggers
[何时调用其他 Agent]

## Critical Rules
[关键约束]

## Success Metrics
[成功指标]

2.4 设计约束

• 格式约束: 必须遵循 SKILL.md 模板
• 性能约束: 发现不能阻塞主流程
• 可读约束: 人类可读，机器可解析

---

三、技术设计

3.1 技能分类

分类	技能数	代表技能
开发工程	15+	ai-engineer, senior-developer, backend-architect
协调管理	8+	agents-orchestrator, project-shepherd
测试质量	6+	code-reviewer, reality-checker, evidence-collector
设计体验	8+	ux-architect, brand-guardian, ui-designer
数据分析	5+	analytics-reporter, performance-benchmarker
社媒营销	12+	twitter-engager, xiaohongshu-specialist
中文平台	5+	chinese-writing, feishu-docs, wechat-oa
XR/空间	4+	visionos-spatial-engineer, xr-immersive-dev

3.2 发现引擎

interface SkillDiscovery {
  // 搜索技能
  search(query: string, options?: SearchOptions): Promise<Skill[]>;

  // 推荐技能
  recommend(context: TaskContext): Promise<Skill[]>;

  // 解析技能文件
  parse(content: string): Skill;

  // 列出所有技能
  listAll(): Promise<Skill[]>;
}

interface Skill {
  name: string;
  description: string;
  triggers: string[];
  tools: string[];
  capabilities: string[];
  collaborationTriggers: string[];
  filePath: string;
}

3.3 发现流程

任务上下文
    │
    ▼
关键词提取
    │
    ├──► 从任务描述提取
    └──► 从历史行为提取
    │
    ▼
技能匹配
    │
    ├──► 触发词匹配
    ├──► 能力匹配
    └──► 语义相似度
    │
    ▼
排序推荐
    │
    ├──► 相关性排序
    ├──► 历史成功率
    └──► 用户偏好
    │
    ▼
返回 Top-N

3.4 协作触发

// 技能可以定义何时调用其他技能
const collaborationTriggers = [
  {
    condition: "任务涉及 UI 设计",
    action: "调用 ux-architect"
  },
  {
    condition: "代码需要审查",
    action: "调用 code-reviewer"
  },
  {
    condition: "部署到生产",
    action: "调用 security-engineer"
  }
];

---

四、预期作用

4.1 用户价值

价值类型	描述
能力扩展	获得专业能力
效率提升	自动匹配技能
质量保证	专业技能保证质量

4.2 系统价值

价值类型	描述
架构收益	可扩展的能力系统
可维护性	标准化易于管理
可扩展性	易于添加新技能

4.3 成功指标

指标	基线	目标	当前
技能数量	0	50+	69
发现准确率	0%	80%	75%
技能使用率	0%	60%	50%

---

五、实际效果

5.1 已实现功能

• 73 个 SKILL.md 技能定义
• 标准化模板
• 发现引擎 (静态注册 12 个核心技能)
• 触发词匹配
• 协作规则
• Playbooks 集成
• SkillMarket UI 组件

5.2 技能分类统计

分类	数量	代表技能
开发工程	15	frontend-developer, backend-architect, ai-engineer
测试/QA	5	code-review, api-tester, accessibility-auditor
设计/UX	5	ui-designer, ux-architect, visual-storyteller
安全	2	security-engineer, legal-compliance-checker
数据分析	5	data-analysis, analytics-reporter, evidence-collector
运维/DevOps	4	devops-automator, infrastructure-maintainer
管理/PM	8	senior-pm, project-shepherd, agents-orchestrator
营销/社媒	12	twitter-engager, xiaohongshu-specialist, zhihu-strategist
内容/写作	4	chinese-writing, translation, content-creator
研究	3	trend-researcher, feedback-synthesizer
商务/销售	3	sales-data-extraction-agent, report-distribution-agent
教育	2	classroom-generator, agentic-identity-trust
核心工具	4	git, file-operations, web-search, shell-command

5.3 实现说明

✅ 已实现动态扫描 (2026-03-24):

• Kernel 集成 SkillRegistry，启动时自动扫描 skills/ 目录
• 前端通过 Tauri 命令 skill_list 获取所有技能
• 支持 skill_refresh 命令重新扫描指定目录
• 73 个技能全部可被发现

数据结构映射:

// 前端 SkillInfo (保留兼容)
interface SkillInfo {
  id: string;
  name: string;
  description: string;
  triggers: string[];      // 从 tags 映射
  capabilities: string[];
  toolDeps: string[];      // 后端暂无
  installed: boolean;      // 从 enabled 映射
  category?: string;       // 从 tags[0] 映射
  version?: string;
  mode?: string;
}

// 后端 SkillManifest (Rust)
struct SkillManifest {
  id: SkillId,
  name: String,
  description: String,
  version: String,
  mode: SkillMode,
  capabilities: Vec<String>,
  tags: Vec<String>,
  enabled: bool,
}

5.4 测试覆盖

• 单元测试: 43 项 (swarm-skills.test.ts)
• 集成测试: 完整流程测试
• 覆盖率: ~90%

5.3 已知问题

问题	严重程度	状态	计划解决
语义匹配精度待提高	中	待优化	Q2
技能质量参差不齐	低	持续改进	-

5.4 用户反馈

技能覆盖全面，但发现准确性需要提高。

---

六、演化路线

6.1 短期计划（1-2 周）

• 优化发现算法
• 添加技能评分

6.2 中期计划（1-2 月）

• 技能市场 UI
• 用户自定义技能

6.3 长期愿景

• 技能共享社区
• 技能认证体系

---

七、头脑风暴笔记

7.1 待讨论问题

1. 是否需要技能版本控制？
2. 如何处理技能冲突？

7.2 创意想法

• 技能组合：多个技能组合成新技能
• 技能学习：从用户行为学习新技能
• 技能热力图：可视化技能使用频率

7.3 风险与挑战

• 技术风险: 技能匹配精度
• 质量风险: 技能定义质量
• 缓解措施: 评分系统，社区审核