[docs] 新增 README: ArtRig Skill 写作规范

README.md

@@ -0,0 +1,150 @@
+# 如何写一个服务于 ArtRig 的 Skill
+
+> 本目录存放**可直接粘贴 / 导入 ArtRig 的 Skill 正文**（Markdown）。本文件是写作规范：讲清 Skill 是什么、注入后长什么样、正文该怎么写、哪些坑必须避开。
+
+---
+
+## 1. Skill 是什么（和风格的区别）
+
+| | 风格（Style） | Skill |
+|---|---|---|
+| 管什么 | **长什么样**：配色、线条、材质、光影等视觉规范 | **怎么干活**：出图流程、质量线、提示词结构、输出格式、何时停下确认 |
+| 存什么 | 结构化字段（`fields[]`），渲染成 `name: value` 行 | **自由 Markdown 正文**（`body`） |
+| 作用域 | 仅项目级 | **项目级 + 全局级** |
+| 注入头部 | `[ARTRIG <slug> @style-<id>/v<n>]` | 项目 `[ARTRIG <slug> @skill-<id>/v<n>]`；全局 `[ARTRIG @global-skill-<id>/v<n>]` |
+
+一句话：**风格定义画风，Skill 定义工作流**。两者可以并行注入，正文里不要重复风格已声明的内容。
+
+参考示例：[`游戏美术.md`](游戏美术.md)（跨项目通用的游戏美术出图流程）。
+
+---
+
+## 2. 存储与文件形态
+
+Git 落位（远端 Gogs）：
+
+```
+projects/<slug>/skills/
+├── index.json          ← 元数据（不含 body）
+├── k1.md               ← 纯 Markdown 正文
+└── k2.md
+
+_global/skills/
+├── index.json
+└── k1.md
+```
+
+- **一个 Skill = 一个 `.md` 文件**，正文就是文件原文：**无 frontmatter、无 JSON 转义、无额外包裹**。
+- 元数据（`id` / `name` / `description` / `version`）只存在 `index.json`，**不要写进 `.md`**。
+- `id` 形如 `k1`、`k2`…，作用域内唯一且稳定（重命名不变）；`id` 即文件名，因此必须是文件名安全字符。
+- 删除以 `index.json` 为准：从 index 移除即可，孤儿 `.md` 不会被加载。
+
+本地缓存与 Git 布局不同（整条含 body 单块 JSON），写 Skill 时无需关心。
+
+---
+
+## 3. 注入后长什么样
+
+调用 `buildSkillPack()`（[`src/core/context-pack.ts`](../src/core/context-pack.ts)）渲染：
+
+```
+[ARTRIG zombie-street @skill-k1/v2]
+三视图出图流程
+<body 正文原样粘贴>
+```
+
+- 头行 + `name` + `body`；
+- **`description` 不注入**（仅用于面板列表辨识）；
+- 头行由扩展自动生成——**正文里不要手写 `[ARTRIG ...]` 行**；
+- `body` 紧跟在 `name` 后面，中间没有任何框架说明。**正文第一段必须自我定义**：说明「以下就是本次对话的工作流规范」。ChatGPT 网页端没有「Skill」这个概念，不定义就会出现指代歧义（详见 §4.2 第 1 条）；
+- 注入通过 `MSG.INJECT_CONTEXT` 追加到当前对话（空则写、非空追加），一次会话只点一次即可。
+
+---
+
+## 4. 正文写作规范
+
+### 4.1 结构
+
+- 用 `##` 分节、`###` 分子节，条目用有序 / 无序列表或表格；避免超过三层的嵌套。
+- 结论先行：把「边界 / 不变量 / 红线」放在最前，细则往后排。
+- 表格用于「触发条件 → 动作 → 交付物」这类映射，比长段落更易被模型执行。
+- **开篇必须先定义自己**（见 §4.2 第 1 条）：不要一上来就写「本 Skill 管什么」——读者（模型）还不知道「本 Skill」指什么。
+
+### 4.2 必须写清楚的几件事
+
+1. **自我定义**：正文第一段用一句 blockquote 钉住自指——「以下文本是本次对话必须遵守的工作流规范（下称『本 Skill』）」。ChatGPT 网页端没有 Skill 概念，不定义就可能被误读成工具、插件、上传文件或上一轮内容。
+2. **主语明确**：条目写「**本 Skill 管** / **本 Skill 不管**」，不要只写「管 / 不管」。
+3. **占位符说明**：`<id>`、`<n>` 这类尖括号会被模型照抄，必须在正文里点明「均为占位符，实际引用时替换为注入头部出现过真实值」。能直接给具体示例（如 `@style-s1/v3`）就少用占位符。
+4. **边界**：本 Skill **管什么、不管什么**。画风一律交给 `@style`，不要在这里定义配色/题材/比例。
+5. **优先级**：`用户当前指令 > 已注入风格 > 本 Skill`，冲突时如何处置。
+6. **标签规则**：只能引用注入头部**真实存在**的标签（`@style-<id>/v<n>`、`@skill-<id>/v<n>`），**禁止自造 id / 版本号**；不确定就先问。
+7. **流程回边**：某阶段不满足条件时回到哪一步（不要只写前进方向）。
+8. **停下确认的时机**：哪些情况必须先问再动手。
+
+### 4.3 不要做的
+
+- ❌ 不要重复风格内容（配色、线条、材质规范由 `@style` 负责）。
+- ❌ 不要在正文里写 `index.json` 的字段、version、id 等元数据。
+- ❌ 不要写死具体项目的 slug、资产名、风格 id（跨项目通用 Skill 尤其注意）。
+- ❌ 不要用**未经定义**的「本 Skill」自指（如开篇第一行就写「本 Skill 的边界」）。
+- ❌ 不要省略主语（「管：…」→ 应为「本 Skill 管：…」）。
+- ❌ 不要不加说明地使用 `<id>` / `<n>` 等占位符。
+- ❌ 不要复述本 Skill 全文或整段 `@style`；引用标签即可。
+- ❌ 不要加 YAML frontmatter（扩展按纯文本处理，不做解析）。
+
+### 4.4 与 ArtRig 数据模型对齐
+
+若 Skill 涉及**回填资产库**，正文里的字段名要直接沿用 ArtRig schema（[`src/core/schema.ts`](../src/core/schema.ts)）：
+
+- 资产字段：`name` / `description` / `keyFeatures` / `palette` / `variants` / `refs` / `tags`
+- 版本操作 `operation`：`generate` / `inpaint` / `cutout` / `split` / `slice` / `layer`
+- 资产版本号形如 `vN`（`^v\d+$`），`final` 是**打在某个 `vN` 上的 tag**，不覆盖历史。
+
+### 4.5 长度
+
+头行 + 正文会整体注入对话，越长越占上下文、越容易被模型忽略尾部。建议：
+
+- 目标 **100–300 行**；
+- 表格 / 清单优先，少用长自然段；
+- 能不写的解释就不写，把「必须遵守的规则」和「可选的说明」分开。
+
+---
+
+## 5. 版本契约
+
+| 操作 | `version` 变化 |
+|------|----------------|
+| 新建 / 复制 | `1` |
+| 修改 `body` 或 `description` | `+1` |
+| 重命名（`name`） | 不变 |
+| 选中 / 注入 | 不变 |
+
+即：**内容（正文/描述）变才升版本**，标识级可追溯，不存内容快照。
+
+---
+
+## 6. 命名与元数据填写
+
+| 字段 | 规范 |
+|------|------|
+| `name` | 中文短名，`trim` 后非空；描述功能不描述画风，如「三视图出图流程」 |
+| `description` | 一句话，说明适用场景；仅列表可见，不注入 |
+| `body` | 本规范第 4 节所述的 Markdown 正文；可为空但不推荐 |
+| `id` | 系统生成 `k1`、`k2`…；不要手动指定 |
+| 作用域 | 只服务单个项目 → 项目级；跨项目复用 → 全局级（`_global/skills`） |
+
+---
+
+## 7. 提交前自检清单
+
+- [ ] 正文没有手写 `[ARTRIG ...]` 头行，也没有 frontmatter / JSON 转义。
+- [ ] **第一段已自我定义「本 Skill」**（用的是定义句，而非「本 Skill 的边界」）。
+- [ ] 条目都有明确主语（「本 Skill 管 / 不管」）。
+- [ ] 占位符 `<id>` / `<n>` 都已说明含义，或已换成具体示例。
+- [ ] 明确写了「管什么 / 不管什么」，画风类内容已交给 `@style`。
+- [ ] 写了优先级与冲突处置方式。
+- [ ] 所有标签引用都来自注入头部，没有自造 id / 版本号。
+- [ ] 流程有回边，不只写前进。
+- [ ] 若涉及回填，字段名与 ArtRig schema 一致（`keyFeatures` / `palette` / `variants` / `refs` / `tags` / `operation`）。
+- [ ] 长度合理（约 100–300 行），表格/清单为主。
+- [ ] 通读一遍：不依赖任何具体项目上下文也能执行。