---
name: skill-development
description: 当需要开发或扩展Jarvis Skill功能时使用此规则——Skill开发规则，Jarvis Skill功能开发规范。包括：遵循Skill开发的标准化流程；设计Skill功能和接口；编写Skill实现代码；实现技能注册和配置；定义技能触发规则和参数；编写技能描述和文档；实现错误处理和异常管理；进行功能分析和需求设计；确保注册信息的一致性；测试技能功能和性能；调试技能运行问题；优化技能执行效率；管理技能依赖和版本；集成技能到Jarvis系统；编写单元测试和集成测试；处理技能间的交互和数据共享。每当用户提及"Skill开发"、"功能扩展"、"插件开发"、"技能添加"或需要Skill开发、功能扩展、插件开发时触发，无论技能类型和复杂度如何。如果需要开发或扩展Jarvis Skill功能，请使用此规则。
---

# 技能开发规则

## 规则简介

本规则定义了技能开发的标准化流程和要求，确保技能添加的规范性、功能分析的准确性。

本规则适用于以下场景：

- **Git仓库技能添加**：从远程Git仓库克隆技能
- **本地路径技能添加**：验证本地技能路径

技能可以是本地路径或Git仓库。Git仓库技能将直接克隆到 `{{ jarvis_data_dir }}/rules/` 目录。

## Jinja2 变量使用指南

### 可用的内置变量

技能文档文件中可以使用以下 Jinja2 模板变量：

| 变量名                                       | 说明                 | 示例值                   |
| -------------------------------------------- | -------------------- | ------------------------ |
| `{% raw %}{{ rule_file_dir }}{% endraw %}`   | 当前规则文件所在目录 | `/path/to/builtin/rules` |
| `{% raw %}{{ git_root_dir }}{% endraw %}`    | Git 仓库根目录       | `/home/user/project`     |
| `{% raw %}{{ current_dir }}{% endraw %}`     | 当前工作目录         | `/home/user/project/src` |
| `{% raw %}{{ jarvis_src_dir }}{% endraw %}`  | Jarvis 源码目录      | `/home/user/jarvis`      |
| `{% raw %}{{ jarvis_data_dir }}{% endraw %}` | Jarvis 数据目录      | `/home/user/.jarvis`     |

**⚠️ 重要提示：**

`{% raw %}{{ rule_file_dir }}{% endraw %}` 表示**当前规则文件所在目录**的绝对路径。引用同目录下的文件时，直接使用 `{% raw %}{{ rule_file_dir }}{% endraw %}/文件名.md`，**不要**重复添加目录层级。

**示例**：如果规则文件在 `builtin/rules/tool_config/` 目录下，引用同目录的 `add_rule.md`，应该写 `{% raw %}{{ rule_file_dir }}{% endraw %}/add_rule.md`，**错误**写法是 `{{ rule_file_dir }}/tool_config/add_rule.md`。

### 变量使用示例

#### 示例 1：在技能文档中引用路径

```markdown
### 技能文件位置

技能文件位于：`{% raw %}{{ jarvis_data_dir }}{% endraw %}/rules/my_skill/`
```

#### 示例 2：动态生成路径

```markdown
### 文档路径

- 技能目录：`{% raw %}{{ jarvis_data_dir }}{% endraw %}/rules/[skill_name]/`
- 技能规则文件：`{% raw %}{{ jarvis_data_dir }}{% endraw %}/rules/[skill_name]/SKILL.md`
```

#### 示例 3：在代码示例中使用变量

```markdown
### 安装命令

`` `bash
cd {% raw %}{{ jarvis_data_dir }}{% endraw %}/rules/my_skill/
pip install -r requirements.txt `` `
```

## 你必须遵守的原则

### 1. 路径验证原则

- **必须**：在处理任何输入前，先验证其有效性
- **必须**：对于Git URL，确认其格式正确
- **必须**：对于本地路径，确认路径存在且可访问
- **禁止**：直接使用未验证的路径或URL

### 2. 技能分析原则

- **必须**：分析技能的核心功能和特性
- **必须**：优先读取README、package.json、setup.py等文档文件
- **必须**：根据技能复杂度选择合适的分析方法
- **禁止**：仅凭文件名或目录名推断功能

**分析策略：**

- **简单技能**（文件数 < 50，有清晰文档）：直接读取关键文件总结功能
- **复杂技能**（文件数 ≥ 50，文档复杂或缺失）：使用`task_list_manager`创建任务列表进行深度分析

## 你必须遵循的工作流程

### 阶段1：输入处理与验证

1. **接收用户输入**（本地路径或Git URL）
2. **判断输入类型**：
   - 如果是Git URL（以`http://`、`https://`、`git@`开头）→ 进入阶段2
   - 如果是本地路径 → 进入阶段3

### 阶段2：Git仓库处理

1. **检查规则目录**：验证`{{ jarvis_data_dir }}/rules`目录是否存在，不存在则创建
2. **提取仓库名称**：从Git URL中提取仓库名称（例如：`https://github.com/user/repo.git` → `repo`）
3. **执行克隆操作**：

   ```bash
   git clone <url> {{ jarvis_data_dir }}/rules/<repo_name>
   ```

4. **处理克隆失败**：询问用户处理方法（重试、更换URL或放弃）
5. **验证克隆结果**：确认克隆后的目录有效

**优化策略：**

- 大仓库使用shallow clone：`git clone --depth 1 <url>`
- 目标目录存在时询问用户是否覆盖

### 阶段3：本地路径验证

1. **路径存在性检查**：确认路径存在
2. **路径可读性验证**：验证路径具有读取权限
3. **错误处理**：路径无效时询问用户确认正确路径

### 阶段4：技能功能分析

1. **关键文档读取**（按优先级）：
   - `README.md`、`README.rst`、`README.txt`
   - `package.json`（Node.js项目）
   - `setup.py`、`pyproject.toml`（Python项目）
   - `Cargo.toml`（Rust项目）
   - `pom.xml`（Java项目）

2. **信息提取分析**：
   - 技能名称识别
   - 核心功能描述
   - 主要特性总结
   - 适用场景分析

3. **复杂度评估**：
   - 统计技能目录文件数量
   - 判断文档完整性
   - 复杂技能使用`task_list_manager`创建深度分析任务

**缺失处理：**

- 文档缺失时基于目录结构推断
- 推断困难时使用基础描述：`[技能名称] - 功能待完善`

## 具体要求和规范

### 1. 输入验证规范

- **Git URL格式**：必须支持`http://`、`https://`、`git@`等标准格式
- **本地路径格式**：必须支持绝对路径和相对路径解析
- **路径有效性**：必须验证路径存在性和访问权限
- **输入类型判断**：必须准确区分Git URL和本地路径

### 2. Git操作规范

- **克隆目录结构**：`{{ jarvis_data_dir }}/rules/<repo_name>`
- **克隆失败处理**：必须提供重试、更换URL、放弃等选项
- **仓库名称提取**：必须从URL中正确解析仓库名称
- **shallow clone优化**：大仓库必须使用`--depth 1`参数

### 3. 技能分析规范

- **文档读取优先级**：README → package.json → setup.py → Cargo.toml → pom.xml
- **信息提取完整性**：必须包含技能名称、功能描述、主要特性、适用场景
- **复杂度评估标准**：文件数量<50为简单技能，≥50为复杂技能
- **分析方法选择**：简单技能直接读取，复杂技能使用`task_list_manager`

### 4. 规则文件格式规范

- **技能规则文件**：`{{ jarvis_data_dir }}/rules/[skill_name]/` 目录下的规则文件（如SKILL.md）
- **顶层规则必须**：作为Skill主入口的规则文件必须包含 YAML front matter header
- **子规则可选**：被主规则引用的详细子规则文件可以不包含 header
- **触发条件说明**：必须在技能规则文件的 YAML front matter 的 description 字段中明确说明触发条件，包括触发关键词、用户意图或适用场景

**触发条件描述要求：**

- **必须**：使用清晰的表述，如"当...时触发"、"每当用户提及...时触发"
- **必须**：明确列出触发关键词或短语
- **必须**：说明适用的业务场景或用户意图
- **禁止**：使用模糊或含糊的触发条件描述

**触发条件描述示例：**

```yaml
---
name: code_review
description: 当用户需要进行代码审查时使用此规则。每当用户提及代码审查、Review代码、检查代码质量或需要进行代码审查、质量检查时触发
license: MIT
---
```

错误示例：

```yaml
---
description: 代码审查规则
---
```

**Header 字段说明：**

- **name**（必填）：技能的唯一标识名称
  - **必须**使用文件名（不含.md后缀）
  - **必须**使用英文或拼音，不建议使用中文
  - 示例：`code_review`, `pptx_generator`

- **description**（必填）：技能的详细触发场景说明
  - **必须**使用清晰的表述说明触发条件
  - **必须**列出触发关键词
  - 示例见上

- **license**（选填）：开源协议标识
  - 常见协议：`MIT`, `Apache-2.0`, `GPL-3.0`
  - 如果不需要特别授权，可以不填写

### 5. 错误处理规范

- **Git克隆失败**：网络检查、URL验证、用户交互处理
- **路径验证失败**：用户确认、拼写检查、重新输入
- **技能分析失败**：基础描述、用户手动输入、功能待完善标记

## 实践指导

### 最佳实践建议

1. **预处理验证**：在执行任何操作前，先进行全面的输入有效性检查
2. **渐进式分析**：从简单文档开始，逐步深入到复杂分析
3. **用户交互优化**：在关键决策点提供清晰的选择和提示
4. **错误恢复机制**：每个阶段都要考虑失败情况和恢复策略

### 性能优化建议

1. **shallow clone使用**：对于大型仓库优先使用浅克隆
2. **文档缓存**：分析过的技能信息可以考虑缓存避免重复分析
3. **并行处理**：多个技能添加时可以考虑批量处理优化

### 质量控制建议

1. **多源验证**：结合多个文档源进行交叉验证
2. **功能完整性检查**：确保提取的功能描述准确全面
3. **格式一致性验证**：规则文件格式必须符合规范

## 执行检查清单

在完成任务后，你必须确认以下项目全部完成：

### 输入验证检查

- [ ] 输入类型判断准确（Git URL或本地路径）
- [ ] Git URL格式验证通过
- [ ] 本地路径存在性和可读性验证通过

### Git操作检查

- [ ] 规则目录结构检查正确（`{{ jarvis_data_dir }}/rules/`）
- [ ] 仓库名称提取准确
- [ ] Git克隆操作执行成功
- [ ] 克隆失败处理机制生效

### 技能分析检查

- [ ] 关键文档文件读取完成
- [ ] 技能功能描述生成准确
- [ ] 复杂度评估标准应用正确
- [ ] 分析方法选择适当

### 质量控制检查

- [ ] Markdown语法正确无错误
- [ ] 规则文件格式符合规范
- [ ] 错误处理机制完备
- [ ] 用户交互流程清晰

## 错误处理规范

### Git克隆失败处理

**必须执行：**

1. **网络连接检查**：验证网络连通性
2. **URL格式验证**：确认Git URL格式正确性
3. **用户交互处理**：提供重试、更换URL、放弃等选项

**处理流程：**

- **重试机制**：允许用户重新执行克隆操作
- **URL更换**：支持用户输入新的Git URL
- **放弃处理**：提供完整的退出机制

### 路径验证失败处理

**必须执行：**

1. **用户确认机制**：询问并确认正确路径
2. **拼写检查提示**：提供路径拼写检查建议
3. **重新输入机会**：允许用户重新输入路径

### 技能分析失败处理

**必须执行：**

1. **基础描述提供**：使用目录名作为技能名称
2. **用户手动输入选项**：允许用户手动提供功能描述
3. **功能待完善标记**：使用"[技能名称] - 功能待完善"标准格式

**降级处理：**

- **文档缺失应对**：基于目录结构进行功能推断
- **分析困难处理**：使用标准化待完善描述
- **用户参与机制**：提供手动输入和确认流程

## 相关资源

- **参考规则**：`{{ rule_file_dir }}/../tool_config/add_rule.md`
- **技能目录**：`{{ jarvis_data_dir }}/rules/`（Git仓库技能和本地技能的统一存储位置）
