malue-ai Skill 创建器
帮助用户创建新的 Skill 或改进已有 Skill。一个 Skill 就是一组指令，教 Agent 如何完成特定任务。
使用场景
- 用户说「帮我做一个 Skill」「把这个流程变成 Skill」「创建一个 XX 技能」
- 用户对某个已有 Skill 不满意，想要改进
- 用户想把当前对话中的成功工作流固化下来
- 用户问「Skill 怎么写」「SKILL.md 格式是什么」
核心流程
创建 Skill 的过程：
- 捕获意图 — 弄清楚用户想让 Skill 做什么
- 访谈研究 — 追问边界情况、输入输出格式、依赖
- 编写 SKILL.md — 生成文件并保存
- 测试验证 — 用几个真实场景测试
- 迭代改进 — 根据反馈优化
你的任务是判断用户在这个流程的哪个阶段，然后帮他推进。
第一步：捕获意图
如果用户想从零开始，先搞清楚这几个问题（可以从对话上下文推断，不必每个都问）：
- 这个 Skill 让 Agent 做什么？ — 核心功能
- 什么时候应该触发这个 Skill？ — 用户说什么话、什么场景
- 输出格式是什么？ — 文件、文本、还是执行动作
- 有什么依赖？ — 需要命令行工具、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 开头：
---
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 的内容分三层加载：
- Metadata（name + description）— 始终在上下文中，约 100 词
- SKILL.md 正文 — Skill 被触发时加载，理想情况 < 500 行
- 附属资源 — 按需读取，无上限
所以 SKILL.md 正文要精炼。超过 500 行时，把详细内容放到 references/ 子目录，正文中用指针引导。
写作原则：
- 解释为什么，而不是堆砌 MUST。今天的 LLM 很聪明，理解了原因比死记规则更有效。如果你发现自己在写"ALWAYS"或"NEVER"（全大写），停下来想想能不能换个方式解释背后的道理。
- 用祈使句。直接说"搜索文件"而不是"你应该搜索文件"。
- 给例子。展示输入和输出的对应关系比长篇描述更清晰。
- 泛化，不要过拟合。Skill 会被用在很多不同场景，不要让指令只适用于某个特定例子。
- 引用能力类别，不要写死 Skill 名。用户可能安装了不同的 Skill 来提供同一种能力。正确：「配合搜索类 Skill 获取信息」「使用 PDF 读取类 Skill」。错误：「配合 ddg-search 搜索」「用 nano-pdf 读取」。如果需要举例帮助理解，用括号补充：「搜索类 Skill（如 jina-reader）」。
- 先写草稿，再审视优化。写完后换个角度看一遍，删掉不必要的内容。
推荐的正文结构：
# Skill 名称（中文）
一句话描述这个 Skill 做什么。
## 使用场景
- 用户说「...」
- 需要做 XX 的时候
## 执行方式
### 方式 1：XXX（首选）
具体步骤和代码示例...
### 方式 2：YYY（备选）
备选方案...
## 输出规范
- 输出格式要求
- 注意事项
依赖声明
如果 Skill 需要外部依赖，在 frontmatter 中声明：
# 需要 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 模板：
---
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 注册模板：
- 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 工具的用法）：
# 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 代码保存文件：
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 后，追加到注册表让系统感知：
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 创建后，验证它能正常工作：
- 构造 2-3 个真实测试场景 — 用户实际会怎么说
- 模拟执行 — 按照 SKILL.md 的指引走一遍流程
- 检查输出 — 是否符合预期
把测试场景和结果告诉用户，让用户确认是否满意。
第五步：迭代改进
根据测试反馈改进 Skill：
- 从反馈中泛化 — 不要只修复特定测试用例，要理解背后的模式
- 保持精简 — 删掉不起作用的内容
- 解释 why — 如果 Agent 总是犯同一个错，与其加"MUST NOT"，不如解释为什么那样做不好
- 提取重复工作 — 如果每次执行都要写同样的脚本，把它放到
scripts/目录
改进已有 Skill
如果用户想改进现有 Skill：
- 先读取现有 SKILL.md 内容
- 了解用户不满意的地方
- 分析问题原因（指令不清楚？缺少边界情况处理？格式不对？）
- 修改并保存
- 测试验证
Description 优化技巧
description 是 Skill 被触发的核心机制。优化原则：
- 包含同义词和常见说法：用户可能用不同的词描述同一件事
- 稍微"积极"一些：当前系统倾向于"少触发"，所以 description 要覆盖面广一点
- 说明 what + when：不仅说做什么，还要说什么情况下用
好的例子：
"生成数据可视化图表。当用户提到图表、柱状图、折线图、饼图、数据可视化、报表生成时使用。"
不好的例子：
"生成图表"
输出规范
- 创建完成后，告知用户 Skill 文件路径和注册状态
- 建议用户试一试新 Skill（给出测试用的话术）
- 如果 Skill 有外部依赖，提醒用户还需要在
config/skills.yaml中注册依赖信息