Skill Creator

Skill开发指南

概述

通过探索打通能力，再提炼为标准化skill。一个skill只做一件事。

Skill类型

• 能力型（capability）：封装具体操作能力，重心在脚本，SKILL.md做调度说明
• 流程型（process）：指导工作流程方法论，重心在SKILL.md本身

Skill形态

单体Skill

功能单一、文件少的skill，平铺结构。

skills/<skill-name>/
  SKILL.md             # 核心文档（给agent看，精简可靠）
  README.md            # 使用说明（给用户看，含prompt示例）
  config.yaml          # 可选，能力型使用，不入库
  config.example.yaml  # 可选，配置模板，入库
  scripts/             # 可选，工具脚本目录
    *.sh / *.py / *.js

Skill Suite（Skills 集合）

多个相关子模块共同组成完整能力时，使用 suite（亦称 skills）结构。

skills/<suite-name>/
  SKILL.md             # Suite入口：总览 + 路由逻辑（引导agent到正确子模块）
  README.md            # 使用说明（整个suite）
  config.example.yaml  # 可选，共享配置模板
  _lib/                # 可选，共享工具脚本（下划线前缀 = 内部基础设施）
    *.sh / *.py
  <module>/            # 子模块目录（每个子模块一个目录）
    SKILL.md           # 子模块文档
    scripts/           # 可选，子模块专属脚本（纯流程型无此目录）
      *.sh / *.py

Suite规范：

• 入口SKILL.md只做总览和路由，不包含具体操作细节
• 子模块各有独立SKILL.md，替代SKILL-<module>.md命名
• 共享工具放_lib/，子模块专属脚本放<module>/scripts/
• config.example.yaml留在suite根目录（配置跨模块共享）

SKILL.md头部格式

---
name: skill名称
description: 一句话描述（含核心动词、关键名词和同义词，用于agent判断何时调用）
metadata:
  type: capability | process
  version: "1.0"
  tags: [标签1, 标签2, 标签3]
  domain: general | devops | ai-infra | documentation
  risk_level: low | medium | high
  platform: linux | windows | macos | cross-platform
---

字段说明：

• name：skill标识，suite子模块格式为 suite-name/module-name
• description：核心触发字段，agent据此判断是否调用。见下方"description编写指南"
• metadata.type：capability（能力型，重脚本）或 process（流程型，重文档）
• metadata.version：语义版本号
• metadata.tags：分类标签，用于索引和搜索
• metadata.domain：所属领域
• metadata.risk_level：操作风险等级（low=只读/分析，medium=修改配置/安装，high=部署/删除/系统级操作）
• metadata.platform：运行平台

description编写指南

description 是 agent 路由的核心依据，必须精心编写：

1. 包含核心动词：用"安装/部署/监控/导出/生成"等动作词开头
2. 列出关键名词：技术栈名称、工具名、协议名等（如 SSH、NPU、Mermaid）
3. 加入同义词：覆盖用户可能的不同表述。如"部署"可同时涵盖 deploy/发布/上线
4. 具体优于笼统：✗ "开发工具集" → ✓ "含CANN/PyTorch/SDK安装、NPU监控、容器部署"
5. 控制长度：一句话，不超过50字

能力型模板

# Skill名称
## 功能（1-2句）
## 配置（config.yaml字段说明）
## 使用（调用脚本的步骤）
## 注意事项（可选）

流程型模板

# Skill名称
## 概述（核心原则1-2句）
## 适用场景
## 流程步骤（编号，每步有明确产出）
## 检查清单（可选）

开发流程

两个阶段：探索 → 提炼。探索阶段可选，已有清晰材料可跳过。

探索阶段（可选）

目标：打通能力，验证可行性。

启动方式灵活：

• 用户主导：用户逐步指令，agent执行反馈
• agent主导：用户描述目标，agent自主探索
• 协作探索：双方交替推进

agent在探索中记录：关键命令、参数、踩坑点、成功路径。

提炼阶段

输入来源：探索阶段的记录 / 用户描述 / 已有文档 / 任意组合。

agent执行：

1. 判断skill类型（能力型 or 流程型）和形态（单体 or suite）
2. 按对应模板生成SKILL.md（精简，去除冗余）
3. 提炼可复用命令为脚本，放入scripts/目录（如适用）
4. 生成config.example.yaml（如适用）
5. 生成README.md（用户导向的使用说明）
6. 输出到 skills// 或 skills// 目录

收尾

验证：新会话中试用skill，确认agent能正确执行

入库：提交到skills/目录

规范约束

• 文档语言：中文
• SKILL.md面向agent：精简、可靠、无冗余说明
• README.md面向用户：使用方法、prompt示例、注意事项
• 能力型SKILL.md ≤ 1KB，流程型 ≤ 3KB，超过则拆分
• 脚本统一放在scripts/目录下（单体skill）或<module>/scripts/下（suite）
• 脚本须自包含、可独立运行、有头部注释（功能、用法、依赖）
• 脚本优先命令行参数，备选从config.yaml读取
• 成功返回0，失败返回非0并输出错误到stderr
• 脚本超过200行 → 考虑拆分
• 禁止具名引用其他skill：每个skill文件夹应可独立拷贝使用。当skill需要某种外部能力（如SSH隧道、反向代理、远程执行等）时，描述"需要什么能力"而非指定具体skill名称，让agent在实际环境的可用skill集合中自行寻找合适的工具。例如：✗ "通过 ssh-dev-suite 的反向代理隧道" → ✓ "通过反向代理隧道（在可用 skill 中寻找提供此功能的工具）"

跨平台规范

• SKILL.md 应在"前置条件"或独立的"运行环境"节中声明目标平台（如 Linux、Windows/macOS/Linux、跨平台）
• 若涉及远程场景，分别声明客户端和服务端平台
• 脚本应能识别运行环境（uname -s / $OSTYPE / platform.system()）并在必要时适配差异
• 跨平台传输文本文件需注意换行符差异（\r\n vs \n）

配置引导规则

• agent执行skill前读取config.yaml，缺失字段交互引导用户填写并回填
• 敏感值按优先级：环境变量 > MCP/外部工具 > 明文（需告知风险）
• 环境变量方式需引导用户按操作系统设置

Token约束

• 探索记录：精简关键命令和结果，不保存完整输出
• 文档生成：一次性写入，不重复展示内容
• 验证测试：只输出关键状态，不粘贴完整日志
• 重复信息：不复述已知内容