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

Skills 系统概述 (Skill System)

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

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

---

一、功能概述

1.1 基本信息

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

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

1.2 Crate 架构

crates/zclaw-skills/
├── src/
│   ├── lib.rs           # Crate 入口
│   ├── registry.rs      # SkillRegistry (HashMap)
│   ├── loader.rs        # SKILL.md 解析器
│   ├── executor.rs      # 技能执行器 (PromptOnly/Python/Shell)
│   ├── orchestration.rs # 技能编排引擎
│   ├── auto_compose.rs  # 自动组合技能
│   └── context.rs       # Context 验证
└── Cargo.toml

待实现:
- WASM 模式执行器
- Native 模式执行器
- input_schema/output_schema 验证

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/	75 个 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 技能分类

分类	技能数	代表技能
开发工程	18+	ai-engineer, senior-developer, backend-architect, frontend-developer
协调管理	10+	agents-orchestrator, project-shepherd, sprint-prioritizer
测试质量	8+	code-reviewer, reality-checker, evidence-collector, api-tester
设计体验	10+	ux-architect, brand-guardian, ui-designer, visual-storyteller
数据分析	6+	analytics-reporter, performance-benchmarker, finance-tracker
社媒营销	15+	twitter-engager, xiaohongshu-specialist, zhihu-strategist
中文平台	6+	chinese-writing, feishu-docs, wechat-oa
XR/空间	5+	visionos-spatial-engineer, xr-immersive-dev, xr-interface-architect
基础工具	5+	web-search, file-operations, shell-command, git
商务销售	4+	sales-data-extraction-agent, report-distribution-agent
教育学习	3+	classroom-generator, agentic-identity-trust
安全合规	3+	security-engineer, legal-compliance-checker
GSD 工作流	20+	gsd:debug, gsd:plan-phase, gsd:execute-phase, gsd:verify-work

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+	75
发现准确率	0%	80%	75%
技能使用率	0%	60%	50%

---

五、实际效果

5.1 已实现功能

• 75 SKILL.md 技能定义
• 标准化模板
• 发现引擎 (动态扫描 75 技能)
• 触发词匹配
• 协作规则
• Playbooks 集成
• SkillMarket UI 组件
• execute_skill 工具 (运行时调用技能)
• 技能分类系统 (11 分类，ID 模式匹配)
• 技能注入 system prompt (自动将技能列表注入)
• PromptOnly/Python/Shell 三种执行模式

5.2 技能分类统计

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

5.3 Crate 实现状态

zclaw-skills crate (80% 完整度):

功能	状态	说明
SkillRegistry	✅	HashMap 存储，O(1) 查找
SKILL.md 解析	✅	YAML frontmatter
skill.toml 解析	✅	简化 TOML 解析器
PromptOnly 执行	✅	直接 prompt 注入
Python 执行	✅	子进程调用
Shell 执行	✅	子进程调用
技能编排	✅	orchestration.rs
自动组合	✅	auto_compose.rs
Context 验证	✅	context.rs
WASM 执行	❌	待实现
Native 执行	❌	待实现
Schema 验证	⚠️	解析但未验证

5.4 测试覆盖

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

5.5 已知问题

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

5.4 用户反馈

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

---

六、演化路线

6.1 短期计划（1-2 周）

• 实现 WASM 执行模式
• 实现 Native 执行模式
• 添加 input_schema/output_schema 验证

6.2 中期计划（1-2 月）

• 技能市场 UI
• 用户自定义技能
• 语义匹配优化

6.3 长期愿景

• 技能共享社区
• 技能认证体系
• 技能版本控制

---

七、头脑风暴笔记

7.1 待讨论问题

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

7.2 创意想法

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

7.3 风险与挑战

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