2.1 目录结构总览

标准目录树

my-skill/                     ← 目录名 = Skill 的 name（必须完全一致）
├── SKILL.md                  ← 唯一必需文件
├── scripts/                  ← 可选
│   ├── main.py
│   └── helper.sh
├── references/               ← 可选
│   ├── api_reference.md
│   └── schema.md
└── assets/                   ← 可选
    ├── template.pptx
    └── logo.png

只有 SKILL.md 是必需的。其余三个目录，不需要就一个都别建——空目录是噪音。

两种存放位置

作用范围 路径 什么时候用
用户级（个人） ~/.workbuddy/skills/<skill-name>/ 默认选择。跨所有项目可用，跟着你走
项目级（团队） <工作区>/.workbuddy/skills/<skill-name>/ 需要随仓库提交、给协作者共享时

Windows 上 ~ 展开为 C:\Users\<用户名>，所以用户级路径实际是：

C:\Users\<用户名>\.workbuddy\skills\<skill-name>\

选择建议：先问「这个 Skill 是我个人习惯，还是团队规范？」 个人习惯 → 用户级；团队规范 / 项目专属数据口径 → 项目级。

命名硬规则（会被校验脚本拒绝）

创建 Skill 目录时，名称必须满足：

规则 说明 反面例子
仅小写字母、数字、连字符 正则表现为 ^[a-z0-9-]+$ MySkill、my_skill、我的技能 ❌
不能以连字符开头/结尾 -skill- ❌ -pdf-tool
不能出现连续连字符 pdf--tool ❌ pdf--tool
长度上限 40 字符 太长不便引用 —
目录名必须与 name 字段完全一致 否则校验器/加载器行为不确定 目录 pdf-tool，字段 pdftool ❌

推荐的命名风格：

  • 动作导向：pdf-watermark、weekly-report、code-review
  • 领域导向：finance-schema、brand-voice
  • 不要用 tools、helper、utils 这类无信息量的名字。

最小可用 Skill

如果只是让 WorkBuddy「记住一个流程」，一个文件就够了：

weekly-report/
└── SKILL.md

内容示例：

---
name: weekly-report
description: 生成团队周报。当用户要求「写周报/周报汇总/本周工作整理/周总结」时使用。
---

# 团队周报生成器

## 输出格式

严格按以下结构输出，不要增删一级标题：

### 一、本周完成
- 每条格式：`[项目] 事项描述（产出物链接）`

### 二、进行中
### 三、风险与阻塞
### 四、下周计划

## 硬规则
1. 每条不超过 50 字，动词开头。
2. 未提供链接的条目，标注「（待补）」，不要编造。
3. 全文用中文，不用 emoji。

这就是一个完整可用的 Skill——没有脚本、没有参考文档，但把「怎么写周报」这件事固定下来了。

幂等与覆盖

  • 同名目录已存在时，init_skill.py 会直接报错退出，不会覆盖——这是保护机制。
  • 要新建请换个名字，或先手动处理旧目录。
  • 修改已有 Skill 时，只改文件内容，不要重建目录。

检查清单

建目录时对照这份清单：

  • [ ] 目录名只含小写字母、数字、连字符
  • [ ] 目录名与 SKILL.md 里的 name 完全一致
  • [ ] 目录只有一层（没有 xxx/xxx/SKILL.md）
  • [ ] SKILL.md 拼写精确（全大写）
  • [ ] 不需要的资源目录一个都没建

上一篇：二、Skill 的内部结构 ｜ 下一篇：2.2 SKILL.md 与 frontmatter 逐字段详解

整理人：WorkBuddy