# writeskilljson

## 规则（Rules）

# 编写 skill.json 规范

## 模板

```json
{
  "name": "技能标识名（英文小写下划线）",
  "title": "技能中文标题",
  "description": "一句话描述，50字以内，含用途和触发关键词",
  "version": "1.0.0",
  "prompt_file": "./skill.md",
  "tools": ["工具名1", "工具名2"]
}
```

## 字段说明

| 字段 | 必填 | 类型 | 说明 |
|------|:----:|:----:|------|
| name | 是 | string | 技能标识名，限英文小写和下划线，不允许中文、数字，全局唯一 |
| title | 是 | string | 技能中文标题，简明扼要 |
| description | 是 | string | 一句话描述，50字以内，包含技能用途和触发关键词 |
| version | 是 | string | 语义化版本号，格式 x.x.x，初始 1.0.0 |
| prompt_file | 是 | string | 技能提示词文件名，固定为 ./skill.md |
| tools | 是 | array[string] | **必填**！技能依赖的所有工具名称列表，不可为空数组 |

## 核心规则

### tools 字段必须填写具体工具名
- **禁止**留空数组 `[]`，必须填写该技能运行所需的全部工具名称
- 工具名来自系统中已有的工具（通过 `get_tool_list` 查询）
- 示例：`"tools": ["read_work", "read_text", "write_text", "make_dir"]`

### description 必须包含触发关键词
- 在描述末尾加上"触发关键词：xxx、xxx"格式
- 示例：`"description": "编写技能配置文件的规范。触发关键词：skill.json、技能配置"`

## 格式要求

- 所有字段名和字符串值必须用双引号包裹
- 数组各项之间用逗号分隔
- 最后一项后面不能有多余逗号
- JSON 标准不支持注释，不得写入 // 或 /* */ 注释
- 文件编码统一为 UTF-8

## 禁止行为
- ❌ 禁止 tools 留空数组（系统无法校验工具依赖）
- ❌ 禁止写入 triggers 字段（系统无此字段）
- ❌ 禁止写入 author 字段（系统无此字段）
- ❌ 禁止在 JSON 中写注释

## 方法（Methods）

# 编写 skill.json 方法

## 步骤

### 1. 查询可用工具
使用 `get_tool_list` 查询系统中已有的所有工具名称，确认该技能依赖的工具都在列表中。

### 2. 确认信息
确认当前技能的以下信息：
- 技能标识名（name）：英文小写下划线，如 write_skill_json
- 技能中文标题（title）：如"技能JSON配置编写"
- 技能描述（description）：50字以内，含用途和触发关键词
- 依赖工具列表（tools）：技能运行所需的**所有**工具名称

### 3. 逐项填写
按模板逐项填入：
- name：填入技能标识名
- title：填入技能中文标题
- description：用一句话描述用途，末尾加"触发关键词：..."，控制在50字内
- version：填入初始版本号 1.0.0
- prompt_file：固定为 ./skill.md
- tools：**必填**，填入技能依赖的所有工具名称数组

### 4. 检查格式
- tools 数组是否已填写具体工具名（非空数组）
- 字段名是否用双引号包裹
- 字符串值是否用双引号包裹
- 数组各项之间是否有逗号
- 最后一项后面是否有多余逗号
- JSON 是否可通过 JSON.parse 校验
- description 是否超过 50 字

## 技巧（Tips）

# 编写 skill.json 技巧

## 1. 工具名要全

从 skill.md 的执行步骤中逐一提取所有出现的工具名，不要遗漏。遗漏工具名会导致智能体运行时缺少工具而报错。

## 2. 快速检查法

填完后从后往前逐项检查：先看最后一项有没有多余逗号，再看数组逗号，再看字段逗号。从后往前检查最容易发现多余逗号。

## 3. 描述卡字数

description 写完后默数一遍，超过 50 字就删修饰词。先写核心用途，再补触发关键词，不够位置就不补。

## 4. 容易踩的坑

- **tools 留空数组**：忘记填工具名，系统无法校验依赖
- name 忘记改成当前技能标识名，直接复制了模板里的示例文本
- description 写了超过 50 字，被系统截断或校验不通过
- version 漏了中间的次版本号，写成 1.0 而不是 1.0.0
- tools 数组漏填了依赖工具，导致技能运行时缺少工具报错
- prompt_file 路径写错，写成了绝对路径或少了 ./ 前缀
- 在 JSON 里写了注释（// 或 /* */），导致 JSON.parse 报错
- 最后一项后面多了逗号，导致 JSON 格式不合法
- **误写 triggers 或 author 字段**（系统无此字段）