@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.
- package/README.md +68 -0
- package/package.json +1 -1
- package/templates/harness/full/.claude/agents/code-reviewer.md +1 -1
- package/templates/harness/full/.claude/agents/harness-reviewer.md +0 -2
- package/templates/harness/full/.claude/rules/skills-mcp.md +2 -3
- package/templates/harness/full/.claude/settings.json +1 -1
- package/templates/harness/full/docs/ai-harness.md +4 -6
- package/templates/harness/full/docs/harness-quick-reference.md +1 -1
- package/templates/harness/full/docs/review-checklist.md +1 -1
- package/templates/harness/full/scripts/verify-skills.mjs +6 -61
- package/templates/harness/full/scripts/verify-skills.test.mjs +1 -11
- package/templates/harness/full/.agents/skills/find-skills/SKILL.md +0 -143
- package/templates/harness/full/.agents/skills/vue-best-practices/LICENSE.md +0 -21
- package/templates/harness/full/.agents/skills/vue-best-practices/SKILL.md +0 -155
- package/templates/harness/full/.agents/skills/vue-best-practices/SYNC.md +0 -5
- package/templates/harness/full/.agents/skills/vue-best-practices/references/animation-class-based-technique.md +0 -258
- package/templates/harness/full/.agents/skills/vue-best-practices/references/animation-state-driven-technique.md +0 -287
- package/templates/harness/full/.agents/skills/vue-best-practices/references/component-async.md +0 -99
- package/templates/harness/full/.agents/skills/vue-best-practices/references/component-data-flow.md +0 -313
- package/templates/harness/full/.agents/skills/vue-best-practices/references/component-fallthrough-attrs.md +0 -179
- package/templates/harness/full/.agents/skills/vue-best-practices/references/component-keep-alive.md +0 -139
- package/templates/harness/full/.agents/skills/vue-best-practices/references/component-slots.md +0 -226
- package/templates/harness/full/.agents/skills/vue-best-practices/references/component-suspense.md +0 -231
- package/templates/harness/full/.agents/skills/vue-best-practices/references/component-teleport.md +0 -110
- package/templates/harness/full/.agents/skills/vue-best-practices/references/component-transition-group.md +0 -131
- package/templates/harness/full/.agents/skills/vue-best-practices/references/component-transition.md +0 -135
- package/templates/harness/full/.agents/skills/vue-best-practices/references/composables.md +0 -303
- package/templates/harness/full/.agents/skills/vue-best-practices/references/directives.md +0 -168
- package/templates/harness/full/.agents/skills/vue-best-practices/references/perf-avoid-component-abstraction-in-lists.md +0 -177
- package/templates/harness/full/.agents/skills/vue-best-practices/references/perf-v-once-v-memo-directives.md +0 -185
- package/templates/harness/full/.agents/skills/vue-best-practices/references/perf-virtualize-large-lists.md +0 -182
- package/templates/harness/full/.agents/skills/vue-best-practices/references/plugins.md +0 -178
- package/templates/harness/full/.agents/skills/vue-best-practices/references/reactivity.md +0 -371
- package/templates/harness/full/.agents/skills/vue-best-practices/references/render-functions.md +0 -227
- package/templates/harness/full/.agents/skills/vue-best-practices/references/sfc.md +0 -355
- package/templates/harness/full/.agents/skills/vue-best-practices/references/state-management.md +0 -138
- package/templates/harness/full/.agents/skills/vue-best-practices/references/updated-hook-performance.md +0 -193
- package/templates/harness/full/AGENTS.md +0 -3
- 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
|
@@ -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 时,必须同步以下
|
|
7
|
+
新增或修改 skill 时,必须同步以下 2 个位置:
|
|
8
8
|
|
|
9
9
|
1. `.claude/skills/{skill}/`
|
|
10
|
-
2.
|
|
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/**`、`.
|
|
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
|
|
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/`
|
|
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
|
|
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
|
|
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}
|
|
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` 维护规则 |
|
|
@@ -3,10 +3,9 @@
|
|
|
3
3
|
* 校验 skills 体系的一致性
|
|
4
4
|
*
|
|
5
5
|
* 检查项:
|
|
6
|
-
* 1. .claude/skills
|
|
7
|
-
* 2.
|
|
8
|
-
* 3.
|
|
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
|
|
168
|
+
// 校验每个 skill 的入口文件和 lock hash
|
|
192
169
|
for (const skillName of skillNames) {
|
|
193
|
-
const
|
|
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)
|
|
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.
|
|
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.
|