3.1 从零创建：初始化与目录规范

路线 A：用官方脚本初始化（推荐）

init_skill.py 会一次性生成正确的目录骨架、SKILL.md 模板、三个资源目录及其示例文件。

用法

python init_skill.py <skill-name> --path <输出目录>

例如，在 Windows 上创建一个用户级 Skill：

python init_skill.py weekly-report --path "C:/Users/Administrator/.workbuddy/skills"

提示：脚本会自行拼接 <输出目录>/<skill-name>，所以 --path 只写到 skills 这一层，不要再手工加上技能名。

生成结果

weekly-report/
├── SKILL.md                    # 带 TODO 占位符的模板
├── scripts/
│   └── example.py              # 示例脚本（可删）
├── references/
│   └── api_reference.md        # 示例参考（可删）
└── assets/
    └── example_asset.txt       # 示例素材（可删）

脚本同时会：

• 校验名称是否合法（不合法直接报错退出）；
• 若目录已存在则拒绝覆盖（保护你的旧工作）；
• 打印后续三步提示（改 SKILL.md、清理示例、跑校验）。

初始化之后必做的三件事

1. 删掉不用的示例：三个目录里只有你真正需要的才留下。空目录要一起删。
2. 重写 description：模板里是 TODO 占位，必须替换（这是最容易被忘的一步）。
3. 删除模板里的「Structuring This Skill」整节：那是给写作者看的提示，不该留在成品里。

路线 B：手工创建

不想用脚本，手动三条命令也行。

mkdir -p "C:/Users/Administrator/.workbuddy/skills/weekly-report"
cd "C:/Users/Administrator/.workbuddy/skills/weekly-report"

然后手工新建 SKILL.md，内容从一个最小骨架开始：

---
name: weekly-report
description: 生成团队周报。TODO：补上「当用户要求……时使用」的触发场景，覆盖口语说法与同义词。
---

# 团队周报生成器

## 概述

用两句话说明这个 Skill 做什么、产出什么、不做什么。

## 工作流程

1. 收集输入
2. 处理
3. 输出

## 硬规则

1. 必须……
2. 禁止……

手工创建更容易出错，常见三个坑详见下面「自检清单」。

命名与位置：动手前先定死

目录名 = name 字段，两者必须一字不差。

创建后的自检清单

• [ ] SKILL.md 文件名全大写，拼写精确
• [ ] 以 --- 开头，frontmatter 用第二个 --- 收尾
• [ ] name 与目录名完全一致，全小写、仅含连字符
• [ ] description 已替换掉 TODO，含「何时使用」
• [ ] 没有多套一层目录（不存在 xxx/xxx/SKILL.md）
• [ ] 不需要的资源目录和示例文件已删除
• [ ] 模板里的指导性文字（TODO、Structuring 段）已清理

常见创建错误对照

上一篇：三、动手制作一个 Skill ｜ 下一篇：3.2 SKILL.md 怎么写

整理人：WorkBuddy