@rockyskills/rw-skills 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +163 -48
  2. package/docs/npm-distribution.md +1 -1
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,99 +1,214 @@
1
1
  # rw-skills
2
2
 
3
- 面向 AI 编程助手的中文 Skill 仓库。把可重复使用的工作方法写成 `SKILL.md`，让助手按明确的步骤完成任务。
3
+ 中文 AI Agent Skill 仓库。将开发协作方法写成可安装、可调用的 Skill，供 AI 编程助手使用。
4
4
 
5
- 仓库地址：[rockywu/rw-skills](https://github.com/rockywu/rw-skills)。目前包含 1 个 Skill，安装方式已在 Codex 的目录结构中验证。
5
+ [GitHub 仓库](https://github.com/rockywu/rw-skills) · [npm 内容包 @rockyskills/rw-skills](https://www.npmjs.com/package/@rockyskills/rw-skills)
6
6
 
7
- ## Skill 列表
7
+ ## 文档目录
8
8
 
9
- | Skill | 中文名称 | 用途 | 介绍 |
10
- |---|---|---|---|
11
- | `traceable-development` | 可追溯开发协作 | 开发计划、任务拆分、依赖与排期、进度、审查证据和 Git 追溯 | [使用说明](traceable-development/README.md) |
9
+ - [工程中的全部 Skill](#工程中的全部-skill)
10
+ - [安装文档](#安装文档)：环境要求、npm 安装、GitHub 安装、安装范围和检查方法。
11
+ - [使用文档](#使用文档)：调用方式、输入资料、使用示例和预期产出。
12
+ - [更新与卸载](#更新与卸载)
13
+ - [新增 Skill](#新增-skill)
14
+ - [发布说明](#发布说明)
12
15
 
13
- ## 安装
16
+ ## 工程中的全部 Skill
14
17
 
15
- 推荐使用 [Vercel Labs skills](https://github.com/vercel-labs/skills) 安装。它是通过 npm 分发的第三方安装工具，本仓库的内容从 GitHub 下载；使用这条路径不需要本仓库发布到 npm。
18
+ 当前工程共 **1 个 Skill**。以下按工程中的 `SKILL.md` 列出完整清单。
16
19
 
17
- 已验证的工具版本为 `skills@1.7.2`，需要 Node.js `>=22.20.0`。
20
+ | Skill 名称 | 中文名称 | 适用任务 | 预期产出 | 详细文档 |
21
+ |---|---|---|---|---|
22
+ | `traceable-development` | 可追溯开发协作 | 开发计划、任务拆分、依赖与排期、进度跟踪、审查和交接 | 沿用项目结构的主计划；按需补充任务卡、需求与任务关联、依赖、验收证据和 Git 记录 | [介绍与示例](https://github.com/rockywu/rw-skills/blob/main/traceable-development/README.md) · [完整规则](https://github.com/rockywu/rw-skills/blob/main/traceable-development/SKILL.md) · [文档模板](https://github.com/rockywu/rw-skills/blob/main/traceable-development/references/templates.md) |
18
23
 
19
- 先查看可安装的 Skill：
24
+ Skill 名称用于安装参数和调用。中文名称用于阅读说明。它不提供后台调度或任务管理服务；实际执行仍由助手依据用户要求完成。
25
+
26
+ ## 安装文档
27
+
28
+ ### 1. 环境要求
29
+
30
+ - 使用 Codex。其他助手的支持范围见 [Vercel Labs skills](https://github.com/vercel-labs/skills)，本仓库目前验证的是 Codex 安装。
31
+ - Node.js `>=22.20.0`，以及可用的 `npm`、`npx`。
32
+ - 能访问 npm registry。使用 GitHub 安装方式时，也需要能访问 GitHub。
33
+
34
+ 检查环境：
35
+
36
+ ```bash
37
+ node --version
38
+ npm --version
39
+ ```
40
+
41
+ 安装使用第三方工具 `skills@1.7.2`。`@rockyskills/rw-skills` 是包含 Skill、介绍和模板的内容包，没有可执行入口。`npm install @rockyskills/rw-skills` 只下载包，不能代替下面的 Skill 安装步骤。
42
+
43
+ ### 2. 从 npm 安装全部 Skill
44
+
45
+ 先取得 npm 当前最新版本的下载地址：
46
+
47
+ ```bash
48
+ rw_skills_tarball="$(npm view @rockyskills/rw-skills dist.tarball --registry=https://registry.npmjs.org/)"
49
+ ```
50
+
51
+ 然后将全部 Skill 全局安装到 Codex，所有项目均可使用：
52
+
53
+ ```bash
54
+ npx --yes skills@1.7.2 add "$rw_skills_tarball" \
55
+ --skill '*' --agent codex --global --copy --yes
56
+ ```
57
+
58
+ 全局目录为 `~/.agents/skills/`。`--skill '*'` 表示安装内容包中的全部 Skill，单引号用于防止 shell 展开星号。当前包只有 `traceable-development`，以后新增 Skill 时不需要逐个填写名称。
59
+
60
+ 如果只需要当前项目使用，在该项目根目录执行下面的命令：
61
+
62
+ ```bash
63
+ npx --yes skills@1.7.2 add "$rw_skills_tarball" \
64
+ --skill '*' --agent codex --copy --yes
65
+ ```
66
+
67
+ 项目目录为 `.agents/skills/`。以上命令中的下载地址变量需在同一个终端中设置。安装前检查同名 Skill；有自定义内容时先备份，再决定是否替换。
68
+
69
+ ### 3. 只安装一个 Skill
70
+
71
+ 使用清单中的名称替换 `--skill '*'`。例如全局安装可追溯开发协作：
72
+
73
+ ```bash
74
+ npx --yes skills@1.7.2 add "$rw_skills_tarball" \
75
+ --skill traceable-development --agent codex --global --copy --yes
76
+ ```
77
+
78
+ 需要固定版本时，取得指定版本的地址即可。例如已经发布的 `0.1.0`：
79
+
80
+ ```bash
81
+ rw_skills_tarball="$(npm view @rockyskills/rw-skills@0.1.0 dist.tarball --registry=https://registry.npmjs.org/)"
82
+ ```
83
+
84
+ ### 4. 从 GitHub 安装
85
+
86
+ 先列出仓库中的全部 Skill：
20
87
 
21
88
  ```bash
22
89
  npx --yes skills@1.7.2 add rockywu/rw-skills --list
23
90
  ```
24
91
 
25
- 在当前项目安装到 Codex：
92
+ 全局安装全部 Skill：
26
93
 
27
94
  ```bash
28
95
  npx --yes skills@1.7.2 add rockywu/rw-skills \
29
- --skill traceable-development --agent codex --copy --yes
96
+ --skill '*' --agent codex --global --copy --yes
97
+ ```
98
+
99
+ 仅安装到当前项目时去掉 `--global`。仅安装单个 Skill 时，将 `'*'` 替换为清单中的 Skill 名称。
100
+
101
+ ### 5. 检查安装结果
102
+
103
+ 全局安装后，应至少存在以下两个文件：
104
+
105
+ ```text
106
+ ~/.agents/skills/traceable-development/SKILL.md
107
+ ~/.agents/skills/traceable-development/references/templates.md
30
108
  ```
31
109
 
32
- 项目安装位置为 `.agents/skills/traceable-development/`。请在目标项目的根目录执行。
110
+ 项目安装时，检查当前项目的 `.agents/skills/traceable-development/`。
33
111
 
34
- 全局安装到 Codex：
112
+ 也可以使用安装工具查看已安装清单：
35
113
 
36
114
  ```bash
37
- npx --yes skills@1.7.2 add rockywu/rw-skills \
38
- --skill traceable-development --agent codex --global --copy --yes
115
+ # 全局安装清单
116
+ npx --yes skills@1.7.2 list --global --agent codex
117
+
118
+ # 当前项目安装清单
119
+ npx --yes skills@1.7.2 list --agent codex
39
120
  ```
40
121
 
41
- 全局安装位置为 `~/.agents/skills/traceable-development/`。安装前检查是否已有同名 Skill；已有自定义内容时先备份。全局命令依据工具文档给出，本次验证使用了临时目录。
122
+ Codex 会自动发现新增 Skill。如果列表中没有出现，可以重启 Codex。手动安装时，也必须复制完整的 Skill 目录，保留 `references/`，不能只复制 `SKILL.md`。
123
+
124
+ ## 使用文档
125
+
126
+ ### 1. 调用 Skill
127
+
128
+ 在 Codex 对话中输入 `$traceable-development`，然后说明目标、范围和约束。在支持 Skill 选择器的界面，也可以选择该 Skill 后发送任务。
129
+
130
+ 安装 Skill 不等于调用它。调用 Skill 也不等于授权推送、合并或发布；需要执行这些操作时，应在任务中说明。
131
+
132
+ ### 2. 提供必要资料
42
133
 
43
- `--copy` 表示复制文件。仓库更新后，本地副本不会自动同步，需要再次安装。其他助手的支持范围见安装工具文档，本仓库目前只验证了 Codex 的安装目录与文件完整性。
134
+ 说明需求或文档位置、当前目标、已有项目约定，以及本次只做规划还是需要执行。已知负责人、期限、验收环境和开发范围时，一并提供；未知项可以让助手标记为待确认。
44
135
 
45
- 也可以让 Codex 的内置 `skill-installer` 从本仓库安装，或手动将完整的 `traceable-development/` 目录复制到项目的 `.agents/skills/` 或用户的 `~/.agents/skills/`。必须保留 `references/`，不能只复制 `SKILL.md`。
136
+ Skill 优先沿用项目现有文档、任务编号和工作流。小任务不强制创建整套文档。
46
137
 
47
- ## 使用
138
+ ### 3. 制定开发计划
48
139
 
49
- 安装后，可以明确指定 Skill，并提供目标、范围和约束：
140
+ 复制下面的内容到 Codex，并将路径、需求和期限替换为项目实际信息：
50
141
 
51
142
  ```text
52
143
  $traceable-development
53
- 请读取项目现有开发文档，将本期需求拆成有稳定编号的任务。
54
- 写清依赖、负责人、验收标准和进度，列出现在可以开始的任务。
55
- 本次只做规划，不执行开发或发布。
144
+ 请读取 docs/requirements.md、已有开发计划和项目约定。
145
+ 为本期需求制定开发计划，沿用现有文档结构。
146
+ 每项任务写清目标、稳定编号、负责人、前置依赖和验收标准。
147
+ 列出当前可以开始的任务和仍需确认的事项。
148
+ 本次只完成规划，不修改业务代码，不推送或发布。
56
149
  ```
57
150
 
58
- 安装不等于已经完成任务，也不等于授权助手推送、合并或发布。Skill 的具体工作规则见 [SKILL.md](traceable-development/SKILL.md)。
151
+ 预期结果：形成或更新一份主计划，需求有对应任务，任务依赖和验收可检查。任务较多时按需补充独立任务卡。
59
152
 
60
- Codex 会自动发现新增的本地 Skill。如果列表中没有出现，可以重启 Codex。目录规则和调用方式见 [OpenAI 官方 Skill 文档](https://developers.openai.com/codex/skills/)。
153
+ ### 4. 更新进度与交接
61
154
 
62
- ## 仓库结构
155
+ ```text
156
+ $traceable-development
157
+ 请读取现有开发计划，核对当前文件、测试证据和 Git 记录。
158
+ 更新任务状态，区分已经实现、已经验收、已经集成和已经部署。
159
+ 记录阻塞原因、解除条件和下一步。
160
+ 列出现在可以开始的任务，并保存接续工作所需的信息。
161
+ 未执行或无法核对的检查请明确标记。
162
+ ```
163
+
164
+ 预期结果：计划与实际证据一致，阻塞有处理方向，接续任务可定位。已提交代码不能自动记为已验收或已部署。
165
+
166
+ ### 5. 按计划执行
63
167
 
64
168
  ```text
65
- rw-skills/
66
- ├── package.json
67
- ├── LICENSE
68
- ├── README.md
69
- ├── docs/
70
- │ └── npm-distribution.md
71
- └── traceable-development/
72
- ├── README.md
73
- ├── SKILL.md
74
- └── references/templates.md
169
+ $traceable-development
170
+ 请按已确认的开发计划执行当前已就绪的任务。
171
+ 先检查依赖是否已经验收并可在目标分支使用。
172
+ 在已授权范围内完成实现和必要验证，并更新计划中的进度与证据。
173
+ 遇到影响范围、业务取舍或权限的未知事项时先询问。
174
+ 本次不推送或发布。
75
175
  ```
76
176
 
77
- 新增 Skill 时，为它建立独立目录，并提供含 `name` 和 `description` 的 `SKILL.md`。使用介绍放在该目录的 `README.md`，辅助模板放在 `references/`。同步更新本页的 Skill 列表。
177
+ 预期结果：实际实现和验证有记录，未完成项如实保留。并行执行需要项目授权及环境支持；给出分工建议不等于已经启动多个任务。
78
178
 
79
- ## npm 分发
179
+ ## 更新与卸载
80
180
 
81
- npm 内容包名称为 `@rockyskills/rw-skills`，归属 `rockyskills` 组织。首版版本为 `0.1.0`，包含中文介绍、Skill 和所需模板。
181
+ `--copy` 会保存本地副本，npm 或 GitHub 内容更新后不会自动同步。更新时重新取得最新下载地址，并重新运行所选安装命令；自定义内容先备份。
82
182
 
83
- 从 npm 的固定版本内容包安装到当前项目的 Codex：
183
+ 卸载全局的可追溯开发协作 Skill：
84
184
 
85
185
  ```bash
86
- npx --yes skills@1.7.2 add \
87
- https://registry.npmjs.org/@rockyskills/rw-skills/-/rw-skills-0.1.0.tgz \
88
- --skill traceable-development --agent codex --copy --yes
186
+ npx --yes skills@1.7.2 remove traceable-development --agent codex --global
187
+ ```
188
+
189
+ 卸载项目版本时，在目标项目根目录执行，并去掉 `--global`。卸载前确认其中没有需要保留的自定义内容。
190
+
191
+ ## 新增 Skill
192
+
193
+ 每个 Skill 使用独立目录：
194
+
195
+ ```text
196
+ skill-name/
197
+ ├── README.md
198
+ ├── SKILL.md
199
+ └── references/
89
200
  ```
90
201
 
91
- 全局安装时，在上述命令增加 `--global`。也可以继续使用 GitHub 安装路径。
202
+ `SKILL.md` 必须包含 `name` 和 `description`。介绍与调用示例放入该 Skill 的 `README.md`，模板放入 `references/`。新增或移除 Skill 时，同步维护本页完整清单，以及 `package.json` 的发布文件白名单。
92
203
 
93
- 包页面：[npm @rockyskills/rw-skills](https://www.npmjs.com/package/@rockyskills/rw-skills)。`npm install` 只下载内容包；使用上面的命令才会把 Skill 放入 Codex 的发现目录。内容包没有可执行入口，不支持直接运行 `npx @rockyskills/rw-skills`。
204
+ ## 发布说明
94
205
 
95
- 两种方式的区别、包配置和发布步骤见 [npm 分发说明](docs/npm-distribution.md)。
206
+ npm 包归属 `rockyskills` 组织。更新已发布的 README 需要发布新的 npm 版本，GitHub 的修改不会自动更新已有 npm 版本的 README。
207
+
208
+ 发布配置与流程见 [npm 分发说明](https://github.com/rockywu/rw-skills/blob/main/docs/npm-distribution.md)。已发布的同版本不能覆盖。
96
209
 
97
210
  ## 许可证
98
211
 
99
- 本仓库及 npm 内容包采用 [MIT License](LICENSE)。使用、修改或分发时，请保留许可证中的版权声明和许可声明。
212
+ 采用 [MIT License](https://github.com/rockywu/rw-skills/blob/main/LICENSE)。使用、修改或分发时，请保留版权声明和许可声明。
213
+
214
+ Codex 的 Skill 目录和调用方式见 [OpenAI 官方文档](https://developers.openai.com/codex/skills/)。
package/docs/npm-distribution.md CHANGED
@@ -46,7 +46,7 @@ npm publish --access public --registry=https://registry.npmjs.org/
46
46
  6. 查询 registry 中的真实版本和下载地址：
47
47
 
48
48
  ```bash
49
- npm view @rockyskills/rw-skills@0.1.0 version dist.tarball \
49
+ npm view @rockyskills/rw-skills version dist.tarball \
50
50
  --registry=https://registry.npmjs.org/
51
51
  ```
52
52
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@rockyskills/rw-skills",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "中文 AI Agent Skills：开发计划、任务依赖与进度追溯",
5
5
  "license": "MIT",
6
6
  "author": "rockywu",