skill-template/development/NAMING.md

技能 slug 命名规范（verb-noun-platform）

本文是匠厂新业务 skill 的 slug / Git 仓库名 / 目录名命名权威说明。复制 skill-template 出去开发新技能前必读；Agent 在开发者询问命名或 slug 时也应先读本文。

---

1. 适用范围

范围	说明
✅ 适用	从 skill-template 复制出去的新技能
❌ 不追溯	已上线历史技能（如 account-manager、reconcile-finance、scrape-contacts-lianjia 等）保持不动
❌ 不修改	其他仓库（尤其 account-manager）不在本文约束范围内
✅ 模板占位	模板本体的 your-skill-slug 占位必须继续通过全部测试

新技能使用「动词-名词」，外部平台可选。不要再为了凑段数追加 default。校验器不追溯已上线仓库；已经发布、末尾是 default 的技能不用改名。

---

2. 命名格式

标准形态：

{verb}-{noun-phrase}
{verb}-{noun-phrase}-{platform}    # 仅当技能绑定外部平台时

部分	规则
verb	1 个词，来自 动词白名单
noun-phrase	1～3 个词（按 - 分段），描述业务对象
platform	可选。没有抖音、小红书、亚马逊这类外部系统时省略。有平台时 1 个词，来自 平台白名单；可含连字符（如 single-window）

展示层分工不变：

字段	语言	示例
slug / repo / 目录 / SKILL_SLUG / DB 文件名	英文 kebab-case	download-settlement-report-amazon
SKILL.md 的 name、description、根 README.md	中文	亚马逊结算报表下载

---

3. 硬约束（新技能强制校验）

约束	值
格式	{verb}-{noun-phrase}；有外部平台时才加 -{platform}
总段数（按 - 分割）	2～5 段
总长度	≤ 48 字符
字符集	小写字母、数字、连字符；kebab-case
禁止	中文 slug、下划线、平台放最前（如 amazon-download-xxx）

实现校验见 scripts/util/slug_naming.py；scripts/db/display_metadata_validator.py 在 SKILL.md frontmatter 自检时调用。

---

4. 三类合法形态

4.1 无平台（常见）

verb-noun 或 verb-noun-noun（2～4 段）

• 第 1 段 ∈ 动词白名单
• 其余为 noun-phrase（1～3 段）
• 不要追加 default

示例：

• generate-monthly-statements
• reconcile-finance
• process-article

4.2 标准型（绑定外部平台）

verb-noun-platform（在无平台形态后加平台，总段数仍 ≤ 5）

• 第 1 段 ∈ 动词白名单
• 最后 1 段（或 hyphenated 平台的最后若干段）∈ 平台白名单
• 中间为 noun-phrase（1～3 段）

示例：

• download-settlement-report-amazon
• add-product-shopee
• enter-sales-receipt-kingdee
• fill-export-declaration-single-window

4.3 scope 型（少见）

verb-noun-scope

• 最后 1 段 ∈ scope 白名单：all | batch | multi
• 第 1 段 ∈ 动词白名单
• 至少还有一段名词（因此最少 3 段）

示例：generate-article-all

default 已从 scope 词表移除。它不是平台，也不表示范围。新技能不要写 generate-article-default 这类占位。已发布且末尾为 default 的仓库保持原 slug；同步本校验后只会警告，不会因此失败。

4.4 历史豁免（不校验语义）

以下 slug 跳过 verb/platform 语义校验（见 LEGACY_EXEMPT_SLUGS）：

• account-manager
• skill-template
• your-skill-slug / your_skill_slug（模板占位）

---

5. 动词白名单

词表文件：assets/naming/verbs.txt（每行一词，便于后续扩展）

动词	动词	动词	动词
scrape	receive	download	export
add	fill	enter	bind
withdraw	reconcile	verify	submit
query	process	reply	generate
draft	review	confirm	track
upload	match	triage	ship
reprice

---

6. 平台白名单

词表文件：assets/naming/platforms.txt

平台	平台	平台
amazon	shopee	xinghang
alibaba	kingdee	icbc
pingpong	worldfirst	paypal
lianlian	single-window	export-rebate
etax

scope 词表：assets/naming/scopes.txt — all、batch、multi。不含 default。

---

7. slug 与展示字段分工

---
name: 亚马逊结算报表下载          # 中文，用户可见
description: "从卖家中心下载结算报表并入库"  # 中文说明
metadata:
  openclaw:
    slug: download-settlement-report-amazon   # 英文机器标识
---

同步修改：

• 目录名
• metadata.openclaw.slug
• scripts/util/constants.py 中的 SKILL_SLUG
• 默认数据库路径 {slug}/{slug}.db

三者必须一致。

---

8. 与 account-manager 的关系

slug 末段 platform 与 account-manager 中的 platform_key 语义对应，但不要求字符串完全相等。

slug 末段 (platform)	account-manager platform_key（示例）
amazon	amazon_sim / amazon
shopee	shopee
kingdee	kingdee

新技能若需账号下发，在 REQUIREMENTS.md §0 填写拟用的 platform_key，并与兄弟技能调用参数对齐。

---

9. 复制新技能流程

1. 先定 slug — {verb}-{noun-phrase}，仅在绑定外部平台时加 -{platform}。确认动词/平台在白名单内且 ≤ 48 字符。不要用 default 占位。
2. 复制目录 — 推荐 tools/scaffold_skill.ps1（-Slug 与目录名一致）；勿整包复制带走 .git 2.5. 清理 Git（若未用 scaffold） — 删除 .git、.openclaw-skill-template、.pytest_cache；再 git init 与 git remote add origin
3. 全局替换 — your-skill-slug → 新 slug；更新 SKILL.md、constants.py、文档中的占位
4. 填写 REQUIREMENTS — 完成 REQUIREMENTS.md §0 技能标识
5. 开发 & 自检 — python tests/run_tests.py -v，含 slug 语义测试；git remote -v 确认非 template

---

10. 正例 / 反例

✅ 正例

slug	说明
generate-monthly-statements	无平台
reconcile-finance	无平台，动词 + 一个名词
download-settlement-report-amazon	有平台
add-product-shopee	有平台
enter-sales-receipt-kingdee	有平台
fill-export-declaration-single-window	有平台，平台含连字符
generate-article-all	scope 型

❌ 反例

slug	原因
amazon-download-settlement-report	平台在最前
enter-cross-border-sales-receipt-voucher-kingdee	过长、noun 臃肿
generate-article-default	default 不是平台；应写成 generate-article
download_settlement_amazon	非 kebab-case（下划线）

---

11. 反模式

• 平台前置：amazon-download-...、shopee-add-...
• 英文占位 name：复制后仍保留 My Skill 或纯英文 slug 风格名称
• 只改目录名：SKILL.md slug 与 constants.SKILL_SLUG 未同步
• 用 default 占位：generate-article-default。没有外部平台就省略末段
• 名词堆砌：中间段过多导致超 48 字符或难以阅读

---

12. 演进说明（当前不启用）

当技能库规模 > 200 时，可再评估引入 {domain}-verb-noun-platform 前缀形态。当前不启用。新技能使用动词-名词；只有绑定外部平台时才使用 verb-noun-platform，或使用 scope 型。

---

13. 历史形态说明

以下为代表性历史 repo，新技能勿仿：

历史 slug	说明
account-manager	跨平台账号管理，非动词-名词
reconcile-finance	现已是合法的无平台形态；旧文档曾把它标成反例
scrape-contacts-lianjia	平台名不在当前白名单（链家）；新技能若要表达链家，先把平台加入白名单
skill-template	模板仓库本身

校验器通过 LEGACY_EXEMPT_SLUGS 对模板占位与少数豁免 slug 跳过语义检查；新复制出去的业务 skill 不在豁免表内，必须满足 §3 硬约束。

---

14. 相关文档

文档	内容
DEVELOPMENT.md	复制模板步骤、发布前检查清单
REQUIREMENTS.md	§0 技能标识必填项
../references/SCHEMA.md	kebab-case 与数据库路径
../SKILL.md	frontmatter 命名摘要