@dianzhong/create-harness-app 0.1.1 → 0.1.3

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 (39) hide show
  1. package/README.md +68 -0
  2. package/package.json +1 -1
  3. package/templates/harness/full/.claude/agents/code-reviewer.md +1 -1
  4. package/templates/harness/full/.claude/agents/harness-reviewer.md +0 -2
  5. package/templates/harness/full/.claude/rules/skills-mcp.md +2 -3
  6. package/templates/harness/full/.claude/settings.json +1 -1
  7. package/templates/harness/full/docs/ai-harness.md +4 -6
  8. package/templates/harness/full/docs/harness-quick-reference.md +1 -1
  9. package/templates/harness/full/docs/review-checklist.md +1 -1
  10. package/templates/harness/full/scripts/verify-skills.mjs +6 -61
  11. package/templates/harness/full/scripts/verify-skills.test.mjs +1 -11
  12. package/templates/harness/full/.agents/skills/find-skills/SKILL.md +0 -143
  13. package/templates/harness/full/.agents/skills/vue-best-practices/LICENSE.md +0 -21
  14. package/templates/harness/full/.agents/skills/vue-best-practices/SKILL.md +0 -155
  15. package/templates/harness/full/.agents/skills/vue-best-practices/SYNC.md +0 -5
  16. package/templates/harness/full/.agents/skills/vue-best-practices/references/animation-class-based-technique.md +0 -258
  17. package/templates/harness/full/.agents/skills/vue-best-practices/references/animation-state-driven-technique.md +0 -287
  18. package/templates/harness/full/.agents/skills/vue-best-practices/references/component-async.md +0 -99
  19. package/templates/harness/full/.agents/skills/vue-best-practices/references/component-data-flow.md +0 -313
  20. package/templates/harness/full/.agents/skills/vue-best-practices/references/component-fallthrough-attrs.md +0 -179
  21. package/templates/harness/full/.agents/skills/vue-best-practices/references/component-keep-alive.md +0 -139
  22. package/templates/harness/full/.agents/skills/vue-best-practices/references/component-slots.md +0 -226
  23. package/templates/harness/full/.agents/skills/vue-best-practices/references/component-suspense.md +0 -231
  24. package/templates/harness/full/.agents/skills/vue-best-practices/references/component-teleport.md +0 -110
  25. package/templates/harness/full/.agents/skills/vue-best-practices/references/component-transition-group.md +0 -131
  26. package/templates/harness/full/.agents/skills/vue-best-practices/references/component-transition.md +0 -135
  27. package/templates/harness/full/.agents/skills/vue-best-practices/references/composables.md +0 -303
  28. package/templates/harness/full/.agents/skills/vue-best-practices/references/directives.md +0 -168
  29. package/templates/harness/full/.agents/skills/vue-best-practices/references/perf-avoid-component-abstraction-in-lists.md +0 -177
  30. package/templates/harness/full/.agents/skills/vue-best-practices/references/perf-v-once-v-memo-directives.md +0 -185
  31. package/templates/harness/full/.agents/skills/vue-best-practices/references/perf-virtualize-large-lists.md +0 -182
  32. package/templates/harness/full/.agents/skills/vue-best-practices/references/plugins.md +0 -178
  33. package/templates/harness/full/.agents/skills/vue-best-practices/references/reactivity.md +0 -371
  34. package/templates/harness/full/.agents/skills/vue-best-practices/references/render-functions.md +0 -227
  35. package/templates/harness/full/.agents/skills/vue-best-practices/references/sfc.md +0 -355
  36. package/templates/harness/full/.agents/skills/vue-best-practices/references/state-management.md +0 -138
  37. package/templates/harness/full/.agents/skills/vue-best-practices/references/updated-hook-performance.md +0 -193
  38. package/templates/harness/full/AGENTS.md +0 -3
  39. package/templates/harness/full/GEMINI.md +0 -3
package/README.md ADDED
@@ -0,0 +1,68 @@
1
+ # @dianzhong/create-harness-app
2
+
3
+ 点众科技前端脚手架。一条命令初始化符合团队规范的 Vue 3 项目。
4
+
5
+ ```bash
6
+ npm create @dianzhong/harness-app my-app
7
+ ```
8
+
9
+ ## 包含内容
10
+
11
+ 基于 [create-vue](https://github.com/vuejs/create-vue) 骨架,叠加:
12
+
13
+ | 层 | 内容 |
14
+ |---|---|
15
+ | **TypeScript + ESLint** | create-vue 默认配置 |
16
+ | **UI 组件库** | Element Plus / Ant Design Vue / 跳过(可选) |
17
+ | **axios 请求层** | 封装好的 `request.ts`、token 管理、统一错误处理 |
18
+ | **AI Harness** | Claude Code hooks(guard-tool + quality-gate)、rules、agents、skills |
19
+
20
+ ## 用法
21
+
22
+ ### 交互模式
23
+
24
+ ```bash
25
+ npm create @dianzhong/harness-app my-app
26
+ # 按提示选择 UI 库、是否集成 axios、Harness 级别
27
+ ```
28
+
29
+ ### 非交互模式(CI / 快速初始化)
30
+
31
+ ```bash
32
+ # 全部默认:TS + Router + Pinia + Element Plus + axios + Harness Full
33
+ npm create @dianzhong/harness-app my-app -- --yes
34
+
35
+ # 自定义
36
+ npm create @dianzhong/harness-app my-app -- --ui=ant-design-vue --harness=minimal
37
+ npm create @dianzhong/harness-app my-app -- --ui=none --harness=none --no-axios
38
+ ```
39
+
40
+ ### 参数
41
+
42
+ | 参数 | 说明 | 默认值 |
43
+ |---|---|---|
44
+ | `--yes` | 非交互,全部使用默认值 | — |
45
+ | `--ui=<lib>` | `element-plus` \| `ant-design-vue` \| `none` | `element-plus` |
46
+ | `--harness=<level>` | `full` \| `minimal` \| `none` | `full` |
47
+ | `--no-axios` | 跳过 axios 请求层 | — |
48
+ | `--vitest` | 启用 Vitest | — |
49
+
50
+ ## 初始化后
51
+
52
+ ```bash
53
+ cd my-app
54
+ pnpm install
55
+ pnpm harness:sync # 计算 skills 指纹(harness:full 时)
56
+ pnpm dev
57
+ ```
58
+
59
+ ## Harness 级别说明
60
+
61
+ - **full** — 完整治理:Claude Code hooks、rules、agents、skills、commit lint、husky、oxlint
62
+ - **minimal** — 轻量守护:guard-tool(阻止危险操作)+ quality-gate(Stop 时自动格式化 + 类型检查)
63
+ - **none** — 不集成,纯 create-vue 骨架 + axios/UI 叠加
64
+
65
+ ## 要求
66
+
67
+ - Node.js `^20.19.0 || >=22.12.0`
68
+ - pnpm(推荐)或 npm / yarn
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@dianzhong/create-harness-app",
3
- "version": "0.1.1",
3
+ "version": "0.1.3",
4
4
  "description": "点众前端项目初始化器:封装 create-vue,叠加 UI 库、axios 层与 AI Harness 治理体系",
5
5
  "type": "module",
6
6
  "bin": {
@@ -11,7 +11,7 @@ tools: Read, Glob, Grep, Bash
11
11
  ## Review 范围
12
12
 
13
13
  - 检查当前 diff 和所有变更文件。
14
- - 阅读 `CLAUDE.md`、`AGENTS.md`,以及相关 `.claude/rules/*.md`。
14
+ - 阅读 `CLAUDE.md` 以及相关 `.claude/rules/*.md`。
15
15
 
16
16
  ### Vue / TypeScript 代码质量
17
17
 
@@ -15,7 +15,6 @@ tools: Read, Glob, Grep, Bash
15
15
  - `.claude/agents/*.md`
16
16
  - `.claude/rules/*.md`
17
17
  - `CLAUDE.md`
18
- - `AGENTS.md`
19
18
  - `docs/ai-harness.md`
20
19
  - `docs/delivery-template.md`
21
20
  - `docs/review-checklist.md`
@@ -32,7 +31,6 @@ tools: Read, Glob, Grep, Bash
32
31
  - Stop review 必须在质量门禁失败或 P0/P1 review 问题时阻止结束。
33
32
  - 完成通知必须兼容 macOS 和 Windows,并在失败时安全降级。
34
33
  - skills 必须同步 lock hash(`skills-lock.json` 中每个 skill 的 `computedHash` 必须与当前文件内容一致)。
35
- - `.agents/skills/` 必须与 `.claude/skills/` 完全镜像(`diff -r .claude/skills/ .agents/skills/` 输出为空)。
36
34
  - harness 脚本的测试必须接入 `pnpm harness:check`,不能只放测试文件。
37
35
  - 结构检查必须只约束通用工程护栏,不得固化当前占位业务流程或 mock 数据。
38
36
  - harness 配置以源文件为准,不维护额外 generated config inventory。
@@ -4,10 +4,9 @@
4
4
  - 项目 skills 放在 `.claude/skills/`。
5
5
  - `skills-lock.json` 必须保存每个 skill 的真实 computed hash。
6
6
 
7
- 新增或修改 skill 时,必须同步以下 3 个位置:
7
+ 新增或修改 skill 时,必须同步以下 2 个位置:
8
8
 
9
9
  1. `.claude/skills/{skill}/`
10
- 2. `.agents/skills/{skill}/`(其他 agent 的镜像)
11
- 3. `skills-lock.json`(hash lock)
10
+ 2. `skills-lock.json`(hash lock)
12
11
 
13
12
  修改任何 skill 后必须先运行 `pnpm harness:sync`,再运行 `pnpm harness:check`。
@@ -81,7 +81,7 @@
81
81
  "hooks": [
82
82
  {
83
83
  "type": "agent",
84
- "prompt": "你是强制 AI harness 代码审查子 agent。审查前先运行 `git diff --name-only` 查看本次改动了哪些文件。若任一改动文件匹配 `.claude/**`、`.agents/**`、`.husky/**`、`scripts/verify-skills.mjs`、`scripts/sync-harness-docs.mjs`、`scripts/check-project-structure.mjs`、`scripts/*.test.mjs`、`skills-lock.json`、`package.json`、`CLAUDE.md`、`AGENTS.md`、`GEMINI.md`、`CONTRIBUTING.md`、`docs/ai-harness.md`、`docs/harness-quick-reference.md`、`docs/delivery-template.md`、`docs/review-checklist.md` 或 `docs/verification.md`,就读取 `.claude/agents/harness-reviewer.md` 并严格按其规则审查;否则读取 `.claude/agents/code-reviewer.md` 并严格按其规则审查。不要编辑任何文件。只返回 JSON:{\"ok\":true|false,\"reason\":\"HARNESS_REVIEW_RESULT: PASS|FAIL\\n简短总结。\"}。并提醒用户:Claude 审查不能替代人工最终复核。",
84
+ "prompt": "你是强制 AI harness 代码审查子 agent。审查前先运行 `git diff --name-only` 查看本次改动了哪些文件。若任一改动文件匹配 `.claude/**`、`.husky/**`、`scripts/verify-skills.mjs`、`scripts/sync-harness-docs.mjs`、`scripts/check-project-structure.mjs`、`scripts/*.test.mjs`、`skills-lock.json`、`package.json`、`CLAUDE.md`、`CONTRIBUTING.md`、`docs/ai-harness.md`、`docs/harness-quick-reference.md`、`docs/delivery-template.md`、`docs/review-checklist.md` 或 `docs/verification.md`,就读取 `.claude/agents/harness-reviewer.md` 并严格按其规则审查;否则读取 `.claude/agents/code-reviewer.md` 并严格按其规则审查。不要编辑任何文件。只返回 JSON:{\"ok\":true|false,\"reason\":\"HARNESS_REVIEW_RESULT: PASS|FAIL\\n简短总结。\"}。并提醒用户:Claude 审查不能替代人工最终复核。",
85
85
  "timeout": 300,
86
86
  "statusMessage": "运行强制代码审查"
87
87
  }
@@ -6,7 +6,7 @@
6
6
 
7
7
  ## 目标
8
8
 
9
- - Claude Code 优先,同时让其他 agent 能从 `AGENTS.md` 读取同一套核心规则。
9
+ - Claude Code 作为唯一执行工具,统一从 `CLAUDE.md` 读取核心规则。
10
10
  - 每次 AI 改动都经过质量门禁和 code review subagent。
11
11
  - hooks 跨 macOS 和 Windows 可用,不依赖 `jq`、`bash` 或平台专属通知命令。
12
12
  - 重要规范进入仓库,可版本化、可 review、可复用。
@@ -14,13 +14,11 @@
14
14
  ## 组成
15
15
 
16
16
  - `CLAUDE.md`:Claude Code 主入口,定义项目事实和执行流程。
17
- - `AGENTS.md`:模型通用入口,降低不同 agent 的理解差异。
18
17
  - `.claude/settings.json`:Claude Code 权限和 hooks 配置。
19
18
  - `.claude/hooks/*.cjs`:跨平台 Node hooks。
20
19
  - `.claude/agents/*.md`:项目级 review subagents。
21
20
  - `.claude/rules/*.md`:可按任务加载的细分规则。
22
21
  - `.claude/skills/`:Claude Code 项目 skills 源。
23
- - `.agents/skills/`:Codex 和其他 agent 使用的项目 skills 镜像。
24
22
  - `scripts/verify-skills.mjs`:校验 skills 文档和 lock 是否同步。
25
23
  - `scripts/sync-harness-docs.mjs`:校验 harness 文档入口是否完整、是否仍引用废弃清单。
26
24
  - `scripts/check-project-structure.mjs`:校验通用前端结构护栏,不固化当前占位业务。
@@ -37,7 +35,7 @@
37
35
  - Hook 行为以 `.claude/hooks/*.cjs` 为准。
38
36
  - Review agent 定义以 `.claude/agents/*.md` 为准;`.claude/settings.json` 中的 Stop agent 内联 prompt 是当前强制 review 入口。
39
37
  - Rules 以 `.claude/rules/*.md` 为准。
40
- - Skills 以 `.claude/skills/` 为源,`.agents/skills/` 为其他 agent 镜像,`skills-lock.json` 保存校验 hash。
38
+ - Skills 以 `.claude/skills/` 为源,`skills-lock.json` 保存校验 hash。
41
39
  - 业务规格以 OpenSpec 的 `openspec/specs/` 为准;待确认或待实现的业务变更以 `openspec/changes/<change-id>/` 为准。
42
40
  - 人工审核交付格式以 `docs/delivery-template.md` 为准。
43
41
 
@@ -60,7 +58,7 @@
60
58
  - `pnpm check:fix`:显式执行格式化与 lint 自动修复。
61
59
  - `pnpm harness:structure`:通用前端结构护栏检查,覆盖 route meta 基础约束、动态菜单组件解析、明显第二套菜单/权限源和高风险 Element Plus 深层覆盖提示。
62
60
  - `pnpm harness:test`:运行 harness 脚本测试,覆盖结构检查、skill 校验和 hooks 基础行为。
63
- - `pnpm harness:check`:skills、docs、lock、入口文档、`.agents/skills` 镜像、项目结构护栏和 harness 脚本测试。
61
+ - `pnpm harness:check`:skills、docs、lock、入口文档、项目结构护栏和 harness 脚本测试。
64
62
  - `pnpm build`:生产构建校验,适用于构建配置、路由、样式或依赖变更。
65
63
 
66
64
  ## 维护规则
@@ -72,6 +70,6 @@
72
70
  - 修改人工审核流程或交付要求时,同步 `docs/review-checklist.md` 和 `docs/delivery-template.md`。
73
71
  - 当前业务代码是占位实现,不允许把项目看板、审核流、mock 数据或临时页面形态沉淀为 harness 规则或工程规范。
74
72
  - 业务规格(页面布局、字段口径、状态机、角色权限矩阵、接口契约等)统一放在 OpenSpec。当前有效规格沉淀到 `openspec/specs/`;PRD 链接、钉钉文档更新或口头需求变更先建 `openspec/changes/<change-id>/`,明确来源、影响页面、接口影响、验收标准和待确认问题。
75
- - OpenSpec 不自动进入 Claude Code 默认上下文,由 AI 按任务需要主动 view。harness 文档(本文件、`docs/harness-quick-reference.md`、`docs/development.md`、`.claude/rules/*`、`CLAUDE.md`、`AGENTS.md`、`GEMINI.md`)只引用 OpenSpec 入口,不复制业务内容。
73
+ - OpenSpec 不自动进入 Claude Code 默认上下文,由 AI 按任务需要主动 view。harness 文档(本文件、`docs/harness-quick-reference.md`、`.claude/rules/*`、`CLAUDE.md`)只引用 OpenSpec 入口,不复制业务内容。
76
74
  - 反复使用的业务规则(全局权限矩阵、跨页面状态机)应做成 `.claude/skills/<name>/`,由 AI 按需加载。
77
75
  - `quality-gate.cjs stop` 是唯一允许自动格式化的 hook,用于 Stop 收尾;其他 hooks 不得自动格式化、暂存或改写 repo-tracked 文件。`lint-staged` 作为 pre-commit safety net 是另一处显式例外。
@@ -82,7 +82,7 @@ OpenSpec 只管理业务规格和需求变更;Harness 继续管理 AI 执行
82
82
  | 步骤 | 检查项 | 参考文档 |
83
83
  | ---- | ----------------------------------------------------------------------------------------------------------- | ----------------------------- |
84
84
  | 1 | 是否修改了 `.claude/settings.json`、hooks、agents、rules、skills?同步入口文档了吗? | `docs/ai-harness.md` 维护规则 |
85
- | 2 | 如果新增或修改 skill,是否同步了 `.claude/skills/{skill}`、`.agents/skills/{skill}` 和 `skills-lock.json`? | `.claude/rules/skills-mcp.md` |
85
+ | 2 | 如果新增或修改 skill,是否同步了 `.claude/skills/{skill}` 和 `skills-lock.json`? | `.claude/rules/skills-mcp.md` |
86
86
  | 3 | 是否运行了 `pnpm harness:sync` 和 `pnpm harness:check`? | `docs/ai-harness.md` 质量门禁 |
87
87
  | 4 | 是否需要按 `docs/verification.md` 做本地浏览器验证? | `docs/verification.md` |
88
88
  | 5 | 是否确认 Stop 收尾不会自动 `git add`? | `docs/ai-harness.md` 维护规则 |
@@ -1,6 +1,6 @@
1
1
  # 人工审核流程
2
2
 
3
- Claude Code 或其他 agent 完成任务后,提交前必须由人做最终复核。AI 的职责是提供可审核的交接单;人的职责是确认业务判断、真实场景和可接受风险。
3
+ Claude Code 完成任务后,提交前必须由人做最终复核。AI 的职责是提供可审核的交接单;人的职责是确认业务判断、真实场景和可接受风险。
4
4
 
5
5
  ## 收到 AI 交接单后
6
6
 
@@ -3,10 +3,9 @@
3
3
  * 校验 skills 体系的一致性
4
4
  *
5
5
  * 检查项:
6
- * 1. .claude/skills .agents/skills 目录结构完全镜像
7
- * 2. SKILL.md 内容 hash 一致
8
- * 3. api/assets/references/scripts/templates 等资源目录内容一致
9
- * 4. skills-lock.json 的 computedHash 与实际目录内容一致
6
+ * 1. .claude/skills 下每个 skill 都有 SKILL.md 入口
7
+ * 2. skills-lock.json 的条目与 .claude/skills 目录完全一致
8
+ * 3. skills-lock.json 的 computedHash 与实际目录内容一致
10
9
  *
11
10
  * --write 模式:更新 skills-lock.json(用于发布 skill 变更时)
12
11
  */
@@ -18,17 +17,8 @@ import path from 'node:path'
18
17
 
19
18
  const root = process.cwd()
20
19
  const skillsDir = path.join(root, '.claude', 'skills')
21
- const agentsSkillsDir = path.join(root, '.agents', 'skills')
22
20
  const lockPath = path.join(root, 'skills-lock.json')
23
21
  const writeMode = process.argv.includes('--write')
24
- const mirroredResourceDirs = new Set([
25
- 'api',
26
- 'assets',
27
- 'examples',
28
- 'references',
29
- 'scripts',
30
- 'templates',
31
- ])
32
22
 
33
23
  const defaultSources = {
34
24
  'element-plus-vue3': {
@@ -103,13 +93,6 @@ async function hashDirectory(dir) {
103
93
  return hash.digest('hex')
104
94
  }
105
95
 
106
- // 计算单个文件的 SHA-256 hash
107
- async function hashFile(filePath) {
108
- const hash = createHash('sha256')
109
- hash.update(await readFile(filePath))
110
- return hash.digest('hex')
111
- }
112
-
113
96
  async function listSkillNames(dir) {
114
97
  if (!existsSync(dir)) {
115
98
  return []
@@ -142,13 +125,7 @@ async function main() {
142
125
  throw new Error(`Missing skills directory: ${skillsDir}`)
143
126
  }
144
127
 
145
- if (!existsSync(agentsSkillsDir)) {
146
- throw new Error(`Missing agents skills mirror directory: ${agentsSkillsDir}`)
147
- }
148
-
149
128
  const skillNames = await listSkillNames(skillsDir)
150
- const agentsSkillNames = await listSkillNames(agentsSkillsDir)
151
- assertEqualSets('.agents/skills mirror entries', new Set(agentsSkillNames), new Set(skillNames))
152
129
 
153
130
  const hashes = {}
154
131
 
@@ -188,46 +165,14 @@ async function main() {
188
165
  const skillNameSet = new Set(skillNames)
189
166
  assertEqualSets('skills-lock.json entries', lockNames, skillNameSet)
190
167
 
191
- // 校验每个 skill 的镜像同步、SKILL.md hash、资源目录和 lock hash
168
+ // 校验每个 skill 的入口文件和 lock hash
192
169
  for (const skillName of skillNames) {
193
- const skillPath = path.join(skillsDir, skillName)
194
- const agentsSkillPath = path.join(agentsSkillsDir, skillName)
195
- const sourceSkillMd = path.join(skillPath, 'SKILL.md')
196
- const mirroredSkillMd = path.join(agentsSkillPath, 'SKILL.md')
170
+ const sourceSkillMd = path.join(skillsDir, skillName, 'SKILL.md')
197
171
 
198
172
  if (!existsSync(sourceSkillMd)) {
199
173
  throw new Error(`Missing skill entrypoint: ${sourceSkillMd}`)
200
174
  }
201
175
 
202
- if (!existsSync(mirroredSkillMd)) {
203
- throw new Error(`Missing mirrored skill entrypoint: ${mirroredSkillMd}`)
204
- }
205
-
206
- if ((await hashFile(sourceSkillMd)) !== (await hashFile(mirroredSkillMd))) {
207
- throw new Error(`Mirrored SKILL.md is out of sync for ${skillName}.`)
208
- }
209
-
210
- for (const resourceDir of mirroredResourceDirs) {
211
- const sourceResourcePath = path.join(skillPath, resourceDir)
212
- const mirroredResourcePath = path.join(agentsSkillPath, resourceDir)
213
-
214
- if (!existsSync(sourceResourcePath)) {
215
- continue
216
- }
217
-
218
- if (!existsSync(mirroredResourcePath)) {
219
- throw new Error(
220
- `Missing mirrored skill resource: ${toPosix(path.relative(root, mirroredResourcePath))}`,
221
- )
222
- }
223
-
224
- if (
225
- (await hashDirectory(sourceResourcePath)) !== (await hashDirectory(mirroredResourcePath))
226
- ) {
227
- throw new Error(`Mirrored skill resource is out of sync: ${skillName}/${resourceDir}`)
228
- }
229
- }
230
-
231
176
  const lockedHash = lock.skills?.[skillName]?.computedHash
232
177
 
233
178
  if (lockedHash !== hashes[skillName]) {
@@ -238,7 +183,7 @@ async function main() {
238
183
  }
239
184
 
240
185
  process.stdout.write(
241
- `Harness skill check passed for ${skillNames.length} skill(s), including .agents/skills mirror.\n`,
186
+ `Harness skill check passed for ${skillNames.length} skill(s).\n`,
242
187
  )
243
188
  }
244
189
 
@@ -4,7 +4,7 @@
4
4
  *
5
5
  * 覆盖:
6
6
  * 1. --write 能生成 lock
7
- * 2. .agents/skills 镜像内容漂移时会失败
7
+ * 2. 生成 lock 后复查通过
8
8
  */
9
9
 
10
10
  import assert from 'node:assert/strict'
@@ -43,7 +43,6 @@ description: Sample skill for harness tests.
43
43
  `
44
44
 
45
45
  await writeFixtureFile(root, '.claude/skills/sample-skill/SKILL.md', skill)
46
- await writeFixtureFile(root, '.agents/skills/sample-skill/SKILL.md', skill)
47
46
 
48
47
  await testFn(root)
49
48
  } finally {
@@ -60,13 +59,4 @@ await withSkillFixture(async (root) => {
60
59
  assert.match(checkResult.stdout, /Harness skill check passed/)
61
60
  })
62
61
 
63
- await withSkillFixture(async (root) => {
64
- assert.equal(runVerify(root, ['--write']).status, 0)
65
- await writeFixtureFile(root, '.agents/skills/sample-skill/SKILL.md', '# Drifted Skill\n')
66
-
67
- const result = runVerify(root)
68
- assert.notEqual(result.status, 0)
69
- assert.match(result.stderr, /Mirrored SKILL\.md is out of sync/)
70
- })
71
-
72
62
  console.log('verify-skills tests passed')
@@ -1,143 +0,0 @@
1
- ---
2
- name: find-skills
3
- description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
4
- ---
5
-
6
- # Find Skills
7
-
8
- This skill helps you discover and install skills from the open agent skills ecosystem.
9
-
10
- ## When to Use This Skill
11
-
12
- Use this skill when the user:
13
-
14
- - Asks "how do I do X" where X might be a common task with an existing skill
15
- - Says "find a skill for X" or "is there a skill for X"
16
- - Asks "can you do X" where X is a specialized capability
17
- - Expresses interest in extending agent capabilities
18
- - Wants to search for tools, templates, or workflows
19
- - Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
20
-
21
- ## What is the Skills CLI?
22
-
23
- The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
24
-
25
- **Key commands:**
26
-
27
- - `npx skills find [query]` - Search for skills interactively or by keyword
28
- - `npx skills add <package>` - Install a skill from GitHub or other sources
29
- - `npx skills check` - Check for skill updates
30
- - `npx skills update` - Update all installed skills
31
-
32
- **Browse skills at:** https://skills.sh/
33
-
34
- ## How to Help Users Find Skills
35
-
36
- ### Step 1: Understand What They Need
37
-
38
- When a user asks for help with something, identify:
39
-
40
- 1. The domain (e.g., React, testing, design, deployment)
41
- 2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
42
- 3. Whether this is a common enough task that a skill likely exists
43
-
44
- ### Step 2: Check the Leaderboard First
45
-
46
- Before running a CLI search, check the [skills.sh leaderboard](https://skills.sh/) to see if a well-known skill already exists for the domain. The leaderboard ranks skills by total installs, surfacing the most popular and battle-tested options.
47
-
48
- For example, top skills for web development include:
49
-
50
- - `vercel-labs/agent-skills` — React, Next.js, web design (100K+ installs each)
51
- - `anthropics/skills` — Frontend design, document processing (100K+ installs)
52
-
53
- ### Step 3: Search for Skills
54
-
55
- If the leaderboard doesn't cover the user's need, run the find command:
56
-
57
- ```bash
58
- npx skills find [query]
59
- ```
60
-
61
- For example:
62
-
63
- - User asks "how do I make my React app faster?" → `npx skills find react performance`
64
- - User asks "can you help me with PR reviews?" → `npx skills find pr review`
65
- - User asks "I need to create a changelog" → `npx skills find changelog`
66
-
67
- ### Step 4: Verify Quality Before Recommending
68
-
69
- **Do not recommend a skill based solely on search results.** Always verify:
70
-
71
- 1. **Install count** — Prefer skills with 1K+ installs. Be cautious with anything under 100.
72
- 2. **Source reputation** — Official sources (`vercel-labs`, `anthropics`, `microsoft`) are more trustworthy than unknown authors.
73
- 3. **GitHub stars** — Check the source repository. A skill from a repo with <100 stars should be treated with skepticism.
74
-
75
- ### Step 5: Present Options to the User
76
-
77
- When you find relevant skills, present them to the user with:
78
-
79
- 1. The skill name and what it does
80
- 2. The install count and source
81
- 3. The install command they can run
82
- 4. A link to learn more at skills.sh
83
-
84
- Example response:
85
-
86
- ```
87
- I found a skill that might help! The "react-best-practices" skill provides
88
- React and Next.js performance optimization guidelines from Vercel Engineering.
89
- (185K installs)
90
-
91
- To install it:
92
- npx skills add vercel-labs/agent-skills@react-best-practices
93
-
94
- Learn more: https://skills.sh/vercel-labs/agent-skills/react-best-practices
95
- ```
96
-
97
- ### Step 6: Offer to Install
98
-
99
- If the user wants to proceed, you can install the skill for them:
100
-
101
- ```bash
102
- npx skills add <owner/repo@skill> -g -y
103
- ```
104
-
105
- The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
106
-
107
- ## Common Skill Categories
108
-
109
- When searching, consider these common categories:
110
-
111
- | Category | Example Queries |
112
- | --------------- | ---------------------------------------- |
113
- | Web Development | react, nextjs, typescript, css, tailwind |
114
- | Testing | testing, jest, playwright, e2e |
115
- | DevOps | deploy, docker, kubernetes, ci-cd |
116
- | Documentation | docs, readme, changelog, api-docs |
117
- | Code Quality | review, lint, refactor, best-practices |
118
- | Design | ui, ux, design-system, accessibility |
119
- | Productivity | workflow, automation, git |
120
-
121
- ## Tips for Effective Searches
122
-
123
- 1. **Use specific keywords**: "react testing" is better than just "testing"
124
- 2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
125
- 3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
126
-
127
- ## When No Skills Are Found
128
-
129
- If no relevant skills exist:
130
-
131
- 1. Acknowledge that no existing skill was found
132
- 2. Offer to help with the task directly using your general capabilities
133
- 3. Suggest the user could create their own skill with `npx skills init`
134
-
135
- Example:
136
-
137
- ```
138
- I searched for skills related to "xyz" but didn't find any matches.
139
- I can still help you with this task directly! Would you like me to proceed?
140
-
141
- If this is something you do often, you could create your own skill:
142
- npx skills init my-xyz-skill
143
- ```
@@ -1,21 +0,0 @@
1
- MIT License
2
-
3
- Copyright (c) 2025 hyf0, SerKo <https://github.com/serkodev>
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.