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 格式

```yaml
---
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 发现引擎

```typescript
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 协作触发

```typescript
// 技能可以定义何时调用其他技能
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 已实现功能

- [x] 75 SKILL.md 技能定义
- [x] 标准化模板
- [x] 发现引擎 (动态扫描 75 技能)
- [x] 触发词匹配
- [x] 协作规则
- [x] Playbooks 集成
- [x] SkillMarket UI 组件
- [x] **execute_skill 工具** (运行时调用技能)
- [x] **技能分类系统** (11 分类，ID 模式匹配)
- [x] **技能注入 system prompt** (自动将技能列表注入)
- [x] **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 风险与挑战
- **技术风险**: 技能匹配精度
- **质量风险**: 技能定义质量
- **缓解措施**: 评分系统，社区审核