# Skill Creator

> Create new skills and improve existing skills. Use when users want to create a skill from scratch, capture a workflow as a skill, update or optimize an existing skill, improve a skill's description for better triggering accuracy, or ask anything about how skills work in this system.

- Skill: `malue-ai/skill-creator-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add malue-ai/skill-creator-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/malue-ai/skill-creator-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: malue-ai (https://skillmd.com/u/malue-ai)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/malue-ai/skill-creator-2

---


# Skill 创建器

帮助用户创建新的 Skill 或改进已有 Skill。一个 Skill 就是一组指令，教 Agent 如何完成特定任务。

## 使用场景

- 用户说「帮我做一个 Skill」「把这个流程变成 Skill」「创建一个 XX 技能」
- 用户对某个已有 Skill 不满意，想要改进
- 用户想把当前对话中的成功工作流固化下来
- 用户问「Skill 怎么写」「SKILL.md 格式是什么」

## 核心流程

创建 Skill 的过程：

1. **捕获意图** — 弄清楚用户想让 Skill 做什么
2. **访谈研究** — 追问边界情况、输入输出格式、依赖
3. **编写 SKILL.md** — 生成文件并保存
4. **测试验证** — 用几个真实场景测试
5. **迭代改进** — 根据反馈优化

你的任务是判断用户在这个流程的哪个阶段，然后帮他推进。

---

## 第一步：捕获意图

如果用户想从零开始，先搞清楚这几个问题（可以从对话上下文推断，不必每个都问）：

1. **这个 Skill 让 Agent 做什么？** — 核心功能
2. **什么时候应该触发这个 Skill？** — 用户说什么话、什么场景
3. **输出格式是什么？** — 文件、文本、还是执行动作
4. **有什么依赖？** — 需要命令行工具、Python 包、API Key、还是纯 LLM 就够

如果用户说「把这个流程变成 Skill」，从当前对话中提取：用了什么工具、执行了什么步骤、用户做了什么修正、输入输出长什么样。

## 第二步：访谈研究

主动追问：

- 边界情况怎么处理？
- 有没有示例文件或参考？
- 成功标准是什么？
- 有没有类似的现有 Skill 可以参考？

如果涉及外部工具或 API，确认依赖信息（命令名、包名、API Key 字段名）。

## 第三步：编写 SKILL.md

### SKILL.md 结构

```
skill-name/
├── SKILL.md          (必需)
├── scripts/          (可选 - 确定性/重复性任务的脚本)
├── references/       (可选 - 按需加载的参考文档)
└── assets/           (可选 - 模板、图标等资源文件)
```

### frontmatter 格式

每个 SKILL.md 必须以 YAML frontmatter 开头：

```yaml
---
name: my-skill-name
description: 清晰描述这个 Skill 做什么、什么时候用它。
metadata:
  xiaodazi:
    dependency_level: builtin    # builtin / lightweight / external / cloud_api
    os: [common]                 # [common] / [darwin] / [win32] / [linux]
    backend_type: local          # local / tool / mcp / api
    user_facing: true
---
```

**字段说明：**

- `name`：唯一标识，小写，用连字符分隔（如 `my-cool-skill`）
- `description`：触发机制的核心。要包含：做什么 + 什么时候用。写得稍微"积极"一些，让 Agent 更容易触发。例如不要写"生成仪表盘"，要写"生成仪表盘。当用户提到数据可视化、报表、图表、监控面板时都应该使用这个 Skill"
- `dependency_level`：
  - `builtin` — 装好就能用，无需额外安装
  - `lightweight` — 需要 pip install 一个包或系统授权
  - `external` — 需要安装外部应用/CLI 工具
  - `cloud_api` — 需要 API Key
- `os`：`[common]` 表示全平台，也可以是 `[darwin]`、`[win32]`、`[linux]`
- `backend_type`：`local` 表示通过 SKILL.md 指导 Agent 执行

### 正文编写指南

**渐进式加载（Progressive Disclosure）**：

Skill 的内容分三层加载：
1. **Metadata**（name + description）— 始终在上下文中，约 100 词
2. **SKILL.md 正文** — Skill 被触发时加载，理想情况 < 500 行
3. **附属资源** — 按需读取，无上限

所以 SKILL.md 正文要精炼。超过 500 行时，把详细内容放到 `references/` 子目录，正文中用指针引导。

**写作原则：**

- **解释为什么，而不是堆砌 MUST**。今天的 LLM 很聪明，理解了原因比死记规则更有效。如果你发现自己在写"ALWAYS"或"NEVER"（全大写），停下来想想能不能换个方式解释背后的道理。
- **用祈使句**。直接说"搜索文件"而不是"你应该搜索文件"。
- **给例子**。展示输入和输出的对应关系比长篇描述更清晰。
- **泛化，不要过拟合**。Skill 会被用在很多不同场景，不要让指令只适用于某个特定例子。
- **引用能力类别，不要写死 Skill 名**。用户可能安装了不同的 Skill 来提供同一种能力。正确：「配合搜索类 Skill 获取信息」「使用 PDF 读取类 Skill」。错误：「配合 ddg-search 搜索」「用 nano-pdf 读取」。如果需要举例帮助理解，用括号补充：「搜索类 Skill（如 jina-reader）」。
- **先写草稿，再审视优化**。写完后换个角度看一遍，删掉不必要的内容。

**推荐的正文结构：**

```markdown
# Skill 名称（中文）

一句话描述这个 Skill 做什么。

## 使用场景

- 用户说「...」
- 需要做 XX 的时候

## 执行方式

### 方式 1：XXX（首选）

具体步骤和代码示例...

### 方式 2：YYY（备选）

备选方案...

## 输出规范

- 输出格式要求
- 注意事项
```

### 依赖声明

如果 Skill 需要外部依赖，在 frontmatter 中声明：

```yaml
# 需要 Python 包
metadata:
  xiaodazi:
    dependency_level: lightweight
    # ...
# 在 skills.yaml 注册时加上：
# python_packages: ["pandas", "openpyxl"]
# auto_install: true

# 需要命令行工具
metadata:
  xiaodazi:
    dependency_level: external
    # ...
# 在 skills.yaml 注册时加上：
# bins: ["ffmpeg"]

# 需要 API Key
metadata:
  xiaodazi:
    dependency_level: cloud_api
    # ...
# 在 skills.yaml 注册时加上：
# api_config: { auth_type: "bearer", auth_key_field: "MY_API_KEY" }
```

### 创建 MCP 类 Skill

当用户想接入一个 MCP Server（如 Screenpipe、Home Assistant、Google Workspace 等），使用 `backend_type: mcp`。

**前提**：用户需要提供 MCP Server 的连接信息。如果用户只说"装一个 chrome-mcp"但不知道 server_url，先解释 MCP 的工作原理，引导用户提供连接信息。

**frontmatter 模板**：

```yaml
---
name: my-mcp-skill
description: 描述这个 MCP Skill 做什么、连接哪个 MCP Server。
metadata:
  xiaodazi:
    dependency_level: external  # 或 cloud_api（如果需要 API Key）
    os: [common]
    backend_type: mcp
    user_facing: true
    api_key_env: MY_MCP_API_KEY  # 可选，如果 MCP Server 需要认证
---
```

**skills.yaml 注册模板**：

```yaml
- name: my-mcp-skill
  backend_type: mcp
  skill_source: instance
  server_url: "http://localhost:3030/mcp"  # 或远程 URL
  server_name: "my-server"                 # MCP Server 标识
  auth_type: "bearer"                      # 可选：bearer / api_key / none
  auth_env: "MY_MCP_API_KEY"               # 可选：存放认证信息的环境变量名
  description: "一句话描述"
```

**SKILL.md 正文结构**（与 local 类 Skill 不同，重点描述 MCP 工具的用法）：

```markdown
# Skill 名称

一句话描述。

## 使用场景
- 用户说「...」

## 前置条件
1. 安装并启动 MCP Server：[安装链接]
2. MCP Server 运行在 `http://localhost:xxxx`
3. [如需认证] 在环境变量中设置 API Key

## 执行方式

### 通过 MCP 工具调用
[列出 MCP Server 提供的工具名称和参数]

### 直接 API 调用（备选）
[如果 MCP Server 也提供 HTTP API，列出备选方式]

## 输出规范
- ...
```

**已有 MCP Skill 参考**：可以读取 `screenpipe`、`deep-doc-reader`、`google-workspace`、`home-assistant` 的 SKILL.md 作为参考。

### 保存文件

确定好内容后，用 `nodes` 工具执行 Python 代码保存文件：

```python
import os
from pathlib import Path

skill_name = "my-skill-name"
instance_name = os.environ.get("AGENT_INSTANCE", "xiaodazi")

# 保存 SKILL.md
skill_dir = Path(f"instances/{instance_name}/skills/{skill_name}")
skill_dir.mkdir(parents=True, exist_ok=True)

skill_content = """---
name: {name}
description: {description}
metadata:
  {instance_name}:
    dependency_level: builtin
    os: [common]
    backend_type: local
    user_facing: true
---

# ...正文...
"""

(skill_dir / "SKILL.md").write_text(skill_content, encoding="utf-8")
print(f"✅ Skill 已保存到 {skill_dir / 'SKILL.md'}")
```

### 注册到 skill_registry.yaml

保存 SKILL.md 后，追加到注册表让系统感知：

```python
import yaml
from pathlib import Path

instance_name = os.environ.get("AGENT_INSTANCE", "xiaodazi")
registry_path = Path(f"instances/{instance_name}/skills/skill_registry.yaml")

registry = yaml.safe_load(registry_path.read_text(encoding="utf-8"))
skills_list = registry.get("skills", [])

# 检查是否已注册
skill_name = "my-skill-name"
if not any(s.get("name") == skill_name for s in skills_list):
    skills_list.append({
        "name": skill_name,
        "enabled": True,
        "status": "ready",
    })
    registry["skills"] = skills_list
    registry_path.write_text(
        yaml.dump(registry, allow_unicode=True, default_flow_style=False),
        encoding="utf-8",
    )
    print(f"✅ 已注册到 {registry_path}")
else:
    print(f"ℹ️ {skill_name} 已在注册表中")
```

注册后，用户下次提到这个 Skill 时，Agent 可以直接按路径读取 SKILL.md 并执行。如果要让它出现在 `<available_skills>` 列表中（无需用户主动提起就能自动匹配），还需要编辑 `instances/{instance_name}/config/skills.yaml`，但这通常不必在创建时立即做。

---

## 第四步：测试验证

Skill 创建后，验证它能正常工作：

1. **构造 2-3 个真实测试场景** — 用户实际会怎么说
2. **模拟执行** — 按照 SKILL.md 的指引走一遍流程
3. **检查输出** — 是否符合预期

把测试场景和结果告诉用户，让用户确认是否满意。

## 第五步：迭代改进

根据测试反馈改进 Skill：

- **从反馈中泛化** — 不要只修复特定测试用例，要理解背后的模式
- **保持精简** — 删掉不起作用的内容
- **解释 why** — 如果 Agent 总是犯同一个错，与其加"MUST NOT"，不如解释为什么那样做不好
- **提取重复工作** — 如果每次执行都要写同样的脚本，把它放到 `scripts/` 目录

---

## 改进已有 Skill

如果用户想改进现有 Skill：

1. 先读取现有 SKILL.md 内容
2. 了解用户不满意的地方
3. 分析问题原因（指令不清楚？缺少边界情况处理？格式不对？）
4. 修改并保存
5. 测试验证

---

## Description 优化技巧

description 是 Skill 被触发的核心机制。优化原则：

- **包含同义词和常见说法**：用户可能用不同的词描述同一件事
- **稍微"积极"一些**：当前系统倾向于"少触发"，所以 description 要覆盖面广一点
- **说明 what + when**：不仅说做什么，还要说什么情况下用

好的例子：
> "生成数据可视化图表。当用户提到图表、柱状图、折线图、饼图、数据可视化、报表生成时使用。"

不好的例子：
> "生成图表"

## 输出规范

- 创建完成后，告知用户 Skill 文件路径和注册状态
- 建议用户试一试新 Skill（给出测试用的话术）
- 如果 Skill 有外部依赖，提醒用户还需要在 `config/skills.yaml` 中注册依赖信息