# Skill Creator

> 用于创建和提炼新skill的元技能，指导从探索到正式skill的全流程

- Skill: `zht043/skill-creator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add zht043/skill-creator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zht043/skill-creator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zht043 (https://skillmd.com/u/zht043)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zht043/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头部格式
```yaml
---
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/<skill-name>/ 或 skills/<suite-name>/ 目录

### 收尾

**验证**：新会话中试用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约束
- 探索记录：精简关键命令和结果，不保存完整输出
- 文档生成：一次性写入，不重复展示内容
- 验证测试：只输出关键状态，不粘贴完整日志
- 重复信息：不复述已知内容