viepilot 2.23.0 → 2.41.0

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 (38) hide show
  1. package/CHANGELOG.md +195 -0
  2. package/README.md +6 -6
  3. package/bin/viepilot.cjs +108 -1
  4. package/bin/vp-tools.cjs +109 -0
  5. package/docs/brainstorm/session-2026-04-20.md +261 -0
  6. package/docs/skills-reference.md +22 -0
  7. package/docs/user/features/adapters.md +2 -2
  8. package/docs/user/features/scaffold-first.md +62 -0
  9. package/docs/user/features/skill-registry.md +125 -0
  10. package/lib/adapters/antigravity.cjs +5 -4
  11. package/lib/skill-installer.cjs +274 -0
  12. package/lib/skill-registry.cjs +212 -0
  13. package/lib/viepilot-update.cjs +113 -0
  14. package/package.json +1 -1
  15. package/skills/vp-audit/SKILL.md +57 -9
  16. package/skills/vp-auto/SKILL.md +44 -0
  17. package/skills/vp-brainstorm/SKILL.md +108 -1
  18. package/skills/vp-crystallize/SKILL.md +72 -0
  19. package/skills/vp-debug/SKILL.md +27 -0
  20. package/skills/vp-docs/SKILL.md +27 -0
  21. package/skills/vp-evolve/SKILL.md +59 -6
  22. package/skills/vp-info/SKILL.md +27 -0
  23. package/skills/vp-pause/SKILL.md +27 -0
  24. package/skills/vp-proposal/SKILL.md +27 -0
  25. package/skills/vp-request/SKILL.md +52 -6
  26. package/skills/vp-resume/SKILL.md +27 -0
  27. package/skills/vp-rollback/SKILL.md +27 -0
  28. package/skills/vp-skills/SKILL.md +301 -0
  29. package/skills/vp-status/SKILL.md +27 -0
  30. package/skills/vp-task/SKILL.md +27 -0
  31. package/skills/vp-ui-components/SKILL.md +27 -0
  32. package/skills/vp-update/SKILL.md +27 -0
  33. package/templates/phase/TASK.md +7 -0
  34. package/templates/project/PROJECT-CONTEXT.md +76 -0
  35. package/workflows/audit.md +131 -0
  36. package/workflows/autonomous.md +140 -0
  37. package/workflows/brainstorm.md +1025 -9
  38. package/workflows/crystallize.md +528 -3
@@ -0,0 +1,261 @@
1
+ # Brainstorm Session — 2026-04-20
2
+
3
+ ## Topic
4
+ **ViePilot Skill Registry System** — Third-party skill installation + scan-skills command + workflow skill integration (brainstorm / crystallize / vp-auto gates)
5
+
6
+ ## Status
7
+ In Progress
8
+
9
+ ---
10
+
11
+ ## Problem Statement
12
+
13
+ ViePilot hiện tại chỉ dùng built-in `vp-*` skills. Khi user muốn xây dựng UI-Direction phức tạp hơn (ví dụ dùng design system cụ thể, component library, hay frontend framework chuyên biệt), không có cơ chế nào để bổ sung context chuyên sâu từ external skills.
14
+
15
+ Vấn đề cụ thể:
16
+ 1. Không có cách cài thêm skills từ bên thứ 3 (npm, GitHub, local)
17
+ 2. ViePilot không biết skills nào đang có sẵn trên máy
18
+ 3. Workflow (brainstorm / crystallize / vp-auto) không thể tận dụng skill context ngoài vp-* namespace
19
+ 4. Quyết định "dùng skill nào" không có điểm lock — vp-auto phải hỏi lại hoặc đoán
20
+
21
+ ---
22
+
23
+ ## Proposed Solution: Skill Registry System
24
+
25
+ ### Core Concept
26
+
27
+ Ba tầng hoạt động:
28
+
29
+ ```
30
+ [Install] vp-tools install-skill <source> → cài skill vào adapter dirs
31
+ [Discover] vp-tools scan-skills → quét + index toàn bộ skills
32
+ [Apply] brainstorm → crystallize → auto → dùng skills theo pipeline
33
+ ```
34
+
35
+ ### Tầng 1 — Installation (multi-channel)
36
+
37
+ `vp-tools install-skill <source>` hỗ trợ:
38
+
39
+ | Channel | Syntax | Example |
40
+ |---------|--------|---------|
41
+ | npm | `npm:package-name` hoặc bare name | `vp-tools install-skill @vp-skills/frontend-design` |
42
+ | GitHub | `github:org/repo` | `vp-tools install-skill github:myorg/vp-skill-tailwind` |
43
+ | Local | `./path` hoặc absolute path | `vp-tools install-skill ./my-skill` |
44
+
45
+ Sau khi install → tự động chạy `scan-skills` để cập nhật registry.
46
+
47
+ Commands bổ sung:
48
+ - `vp-tools uninstall-skill <id>` — xóa khỏi tất cả adapter dirs
49
+ - `vp-tools list-skills` — hiển thị skills đã cài + version + source
50
+ - `vp-tools update-skill <id>` — cập nhật từ source gốc
51
+
52
+ ### Tầng 2 — Scanner & Registry
53
+
54
+ `vp-tools scan-skills` quét toàn bộ adapter dirs:
55
+ - `~/.claude/skills/` (Claude Code)
56
+ - `~/.cursor/skills/` (Cursor)
57
+ - `~/.codex/skills/` (Codex)
58
+ - `~/.antigravity/skills/` (Antigravity)
59
+
60
+ Output: `~/.viepilot/skill-registry.json`
61
+
62
+ ```json
63
+ {
64
+ "version": "1.0",
65
+ "last_scan": "2026-04-20T10:30:00Z",
66
+ "scan_paths": ["~/.claude/skills/", "~/.cursor/skills/"],
67
+ "skills": [
68
+ {
69
+ "id": "frontend-design",
70
+ "name": "Frontend Design",
71
+ "source": "npm:@vp-skills/frontend-design",
72
+ "version": "1.2.0",
73
+ "description": "...",
74
+ "capabilities": ["ui-generation", "component-design", "responsive-layout"],
75
+ "tags": ["ui", "design", "frontend", "css", "html"],
76
+ "best_practices": ["Mobile-first", "Design tokens", "BEM naming"],
77
+ "adapters": ["claude-code", "cursor"],
78
+ "installed_paths": {
79
+ "claude-code": "~/.claude/skills/frontend-design/",
80
+ "cursor": "~/.cursor/skills/frontend-design/"
81
+ }
82
+ }
83
+ ]
84
+ }
85
+ ```
86
+
87
+ ### Tầng 3 — SKILL.md Extended Format
88
+
89
+ Third-party skills (và vp-* skills nếu muốn) thêm 3 sections mới vào SKILL.md:
90
+
91
+ ```markdown
92
+ ## Capabilities
93
+ - ui-generation
94
+ - component-design
95
+ - responsive-layout
96
+
97
+ ## Tags
98
+ ui, design, frontend, css, html, tailwind
99
+
100
+ ## Best Practices
101
+ - Use design tokens for consistency across components
102
+ - Mobile-first: design breakpoints from 320px up
103
+ - BEM naming convention for CSS classes
104
+ ```
105
+
106
+ Scanner đọc các sections này để index. Skills không có sections mới vẫn được scan (fallback: parse description + content tự động).
107
+
108
+ ### Tầng 4 — Workflow Integration Pipeline
109
+
110
+ #### A. Brainstorm → Silent Skill Application (UI-Direction)
111
+
112
+ Khi brainstorm có UI signals (keywords: `component`, `design`, `layout`, `screen`, `UI`, v.v.):
113
+ - Load `~/.viepilot/skill-registry.json`
114
+ - Match skills có `capabilities` phù hợp (e.g., `ui-generation`, `component-design`)
115
+ - **Silent apply**: tự động include best practices từ matched skills vào HTML generation
116
+ - Record vào `notes.md`: `## skills_used` section
117
+
118
+ ```yaml
119
+ ## skills_used
120
+ - id: frontend-design
121
+ version: 1.2.0
122
+ trigger: ui-generation signal
123
+ applied_at: brainstorm-session
124
+ best_practices_applied:
125
+ - Mobile-first
126
+ - Design tokens
127
+ ```
128
+
129
+ Không hỏi user — chạy ngầm như Background UI Extraction.
130
+
131
+ #### B. Crystallize → Skill Decision Lock Gate
132
+
133
+ Bước mới trong `vp-crystallize` (sau scope lock, trước generate SPEC):
134
+
135
+ 1. Đọc `notes.md` → `## skills_used` của session đó
136
+ 2. Hiển thị danh sách skills đã/sẽ được dùng
137
+ 3. User confirm: required vs optional per phase/task
138
+ 4. Ghi vào `PROJECT-CONTEXT.md`:
139
+
140
+ ```markdown
141
+ ## Skills
142
+
143
+ | Skill | Source | Required | Phases | Rationale |
144
+ |-------|--------|----------|--------|-----------|
145
+ | frontend-design | npm:@vp-skills/frontend-design | required | 1, 2 | UI-Direction HTML generation — design token best practices |
146
+ | tailwind-guide | github:org/vp-tailwind | optional | 2 | Phase 2 styling layer |
147
+ ```
148
+
149
+ **Lý do lock ở crystallize:** vp-auto là execution-only — nó đọc SPEC và chạy, không ra quyết định. Tất cả quyết định về "dùng skill nào" phải được lock trước khi vp-auto bắt đầu.
150
+
151
+ #### C. vp-auto → Silent Skill Execution
152
+
153
+ vp-auto đọc `## Skills` từ `PROJECT-CONTEXT.md`:
154
+ - Với mỗi task, kiểm tra skills `required` trong phases tương ứng
155
+ - Load best practices từ skill registry
156
+ - Include context vào execution prompt — **không hỏi lại user**
157
+ - Ghi vào task output: `skills_applied: [frontend-design@1.2.0]`
158
+
159
+ ---
160
+
161
+ ## Decisions
162
+
163
+ | Decision | Options Considered | Chosen | Rationale |
164
+ |----------|--------------------|--------|-----------|
165
+ | Skill source channels | npm-only / all channels | All channels (npm + github + local) | Flexibility cho cả published và WIP skills |
166
+ | Scanner scope | ViePilot-only dirs / all adapter dirs | All adapter dirs | Discover tất cả skills user đã cài qua bất kỳ tool nào |
167
+ | Gate model | Required block / heuristic prompt / silent / hybrid | Silent auto-apply + crystallize-time lock | vp-auto không hỏi lại; quyết định từ crystallize. Nhất quán với ui-direction guard |
168
+ | SKILL.md format | Giữ nguyên / extend / file riêng | Extend — thêm Capabilities/Tags/Best Practices | Backward compat; scanner vẫn parse skills cũ |
169
+ | Lock storage | SPEC.md per-task / PROJECT-CONTEXT.md ## Skills / file riêng | PROJECT-CONTEXT.md ## Skills | Tương tự ## Tech Stack — project-level; dễ đọc cho vp-auto |
170
+ | Phase 1 target | Scanner / Installer / Brainstorm integration | Scanner + registry first | Nền tảng cho mọi tính năng phía sau |
171
+
172
+ ---
173
+
174
+ ## Open Questions
175
+
176
+ | ID | Question | Priority | Due |
177
+ |----|----------|----------|-----|
178
+ | Q1 | Có cần `vp-tools publish-skill` để user publish skill lên npm không? | low | next milestone |
179
+ | Q2 | Skill versioning: nếu skill update, best practices thay đổi — có cần re-crystallize không? | medium | Phase 4 design |
180
+ | Q3 | Skill conflict: 2 skills có cùng capability, workflow ưu tiên cái nào? | medium | Phase 3 design |
181
+ | Q4 | Có cần một "official ViePilot skills registry" (marketplace) hay chỉ dựa vào npm search? | low | future |
182
+
183
+ ---
184
+
185
+ ## Phases
186
+
187
+ ### Phase 1 — Skill Registry Foundation
188
+ **Goal**: `vp-tools scan-skills` + `~/.viepilot/skill-registry.json` + extended SKILL.md format spec
189
+
190
+ Tasks:
191
+ 1. `lib/skill-registry.cjs` — scanner: traverse adapter dirs, parse SKILL.md (extended + legacy), build JSON
192
+ 2. `bin/viepilot.cjs` — add `scan-skills` subcommand + `list-skills` display
193
+ 3. `docs/user/features/skill-registry.md` — extended SKILL.md format spec + scanner docs
194
+ 4. `tests/unit/vp-skill-registry.test.js` — 15+ contract tests (scan, parse, index, legacy compat)
195
+
196
+ Target version: **2.26.0**
197
+
198
+ ### Phase 2 — Third-party Skill Installation
199
+ **Goal**: `vp-tools install-skill` (npm + github + local) + `uninstall-skill` + `update-skill`
200
+
201
+ Tasks:
202
+ 1. `lib/skill-installer.cjs` — multi-channel installer (npm exec + git clone + fs copy)
203
+ 2. `bin/viepilot.cjs` — add `install-skill`, `uninstall-skill`, `update-skill` subcommands
204
+ 3. Post-install hook: auto-run `scan-skills`
205
+ 4. `tests/unit/vp-skill-installer.test.js` — 12+ tests (each channel, auto-scan trigger)
206
+
207
+ Target version: **2.27.0**
208
+
209
+ ### Phase 3 — Brainstorm Integration (UI-Direction silent apply)
210
+ **Goal**: brainstorm.md detects UI signals → loads registry → silently applies matched skill best practices → records `## skills_used` in notes.md
211
+
212
+ Tasks:
213
+ 1. `workflows/brainstorm.md` — add skill registry load step + signal matching logic + silent apply rule
214
+ 2. `skills/vp-brainstorm/SKILL.md` — document skill integration behavior
215
+ 3. `tests/unit/brainstorm-skill-integration.test.js` — 10+ tests
216
+
217
+ Target version: **2.28.0**
218
+
219
+ ### Phase 4 — Crystallize Skill Decision Gate
220
+ **Goal**: crystallize.md new step → skill confirmation gate → `## Skills` in PROJECT-CONTEXT.md
221
+
222
+ Tasks:
223
+ 1. `workflows/crystallize.md` — add skill gate step (read notes.md skills_used → AUQ confirm → write PROJECT-CONTEXT.md)
224
+ 2. `templates/project/PROJECT-CONTEXT.md` — add `## Skills` section template
225
+ 3. `skills/vp-crystallize/SKILL.md` — document skill gate
226
+ 4. `tests/unit/crystallize-skill-gate.test.js` — 10+ tests
227
+
228
+ Target version: **2.29.0**
229
+
230
+ ### Phase 5 — vp-auto Silent Skill Execution
231
+ **Goal**: autonomous.md reads `## Skills` from PROJECT-CONTEXT.md → per-task silent context injection
232
+
233
+ Tasks:
234
+ 1. `workflows/autonomous.md` — add skill context load step + per-task skill injection rule
235
+ 2. `skills/vp-auto/SKILL.md` — document silent skill execution
236
+ 3. `tests/unit/autonomous-skill-execution.test.js` — 8+ tests
237
+
238
+ Target version: **2.30.0**
239
+
240
+ ---
241
+
242
+ ## Background UI Extraction
243
+
244
+ Waiver — session topic is a framework feature (skill registry), not a consumer app UI. No UI Direction artifacts needed.
245
+
246
+ ---
247
+
248
+ ## Project meta intake (FEAT-009)
249
+
250
+ Waiver — ViePilot framework repo; profile binding already exists.
251
+
252
+ ---
253
+
254
+ ## Session Summary
255
+
256
+ - **Feature**: ViePilot Skill Registry System
257
+ - **Suggested ID**: FEAT-020
258
+ - **Scope**: 5 phases — registry/scanner → installer → brainstorm integration → crystallize gate → vp-auto execution
259
+ - **Key architectural decision**: Skills are **silent auto-apply** at brainstorm time; **locked at crystallize** time; **executed without re-asking** by vp-auto
260
+ - **Backward compat**: Existing SKILL.md files still work — scanner gracefully handles missing extended sections
261
+ - **First deliverable**: `vp-tools scan-skills` + `~/.viepilot/skill-registry.json` (Phase 1 → v2.26.0)
@@ -525,3 +525,25 @@ Place custom `.pptx`/`.docx` files in `.viepilot/proposal-templates/` to overrid
525
525
  ```
526
526
 
527
527
  Full guide: `docs/user/features/proposal.md`
528
+
529
+ ---
530
+
531
+ ## /vp-skills
532
+
533
+ **Purpose**: Agent-native global skill registry management — scan, list, install, uninstall, update, and inspect third-party skills from any project directory (ENH-062).
534
+
535
+ ### Commands
536
+ | Command | Description |
537
+ |---------|-------------|
538
+ | `/vp-skills scan` | Refresh `~/.viepilot/skill-registry.json` by scanning all adapter dirs |
539
+ | `/vp-skills list` | Display indexed skills table |
540
+ | `/vp-skills install <src>` | Install from npm / `github:<user>/<repo>` / local path |
541
+ | `/vp-skills uninstall <id>` | Remove skill from all adapter directories |
542
+ | `/vp-skills update <id>` | Re-install from original source (`skill-meta.json`) |
543
+ | `/vp-skills info <id>` | Show capabilities, best_practices, and adapter paths |
544
+
545
+ ### Notes
546
+ - Uses installed vp-tools binary (`~/.claude/viepilot/bin/vp-tools.cjs`) — works from any project directory.
547
+ - Fallback: `~/.cursor/viepilot/bin/vp-tools.cjs` for Cursor adapter.
548
+ - Registry file: `~/.viepilot/skill-registry.json` — shared across all projects.
549
+ - Confirmation AUQ prompt before destructive `uninstall` (Claude Code terminal only).
@@ -8,7 +8,7 @@ ViePilot supports multiple AI coding platforms via its adapter system (FEAT-013)
8
8
  |------------|----------|------------|--------------|-------|--------------|
9
9
  | `claude-code` | Claude Code *(default)* | `~/.claude/skills/` | `~/.claude/viepilot/` | ✅ Stop, PreToolUse, … | `/vp-status` |
10
10
  | `cursor-agent` / `cursor-ide` | Cursor | `~/.cursor/skills/` | `~/.cursor/viepilot/` | — | `/vp-status` |
11
- | `antigravity` | Google Antigravity | `~/.antigravity/skills/` | `~/.antigravity/viepilot/` | — | `/vp-status` |
11
+ | `antigravity` | Google Antigravity | `~/.gemini/antigravity/skills/` | `~/.gemini/antigravity/viepilot/` | — | `/vp-status` |
12
12
  | `codex` | OpenAI Codex CLI | `~/.codex/skills/` | `~/.codex/viepilot/` | — | `$vp-status` |
13
13
  | `copilot` | GitHub Copilot | `~/.config/gh-copilot/skills/` | `~/.config/gh-copilot/viepilot/` | — | `/vp-status` |
14
14
 
@@ -47,7 +47,7 @@ Skill source files use the neutral placeholder `{envToolDir}` in `execution_cont
47
47
  At install time, `{envToolDir}` is replaced with each adapter's `executionContextBase`:
48
48
  - `claude-code` → `.claude/viepilot`
49
49
  - `cursor` → `.cursor/viepilot`
50
- - `antigravity` → `.antigravity/viepilot`
50
+ - `antigravity` → `.gemini/antigravity/viepilot`
51
51
  - `codex` → `.codex/viepilot`
52
52
  - `copilot` → `.config/gh-copilot/viepilot`
53
53
 
@@ -0,0 +1,62 @@
1
+ # Scaffold-First Gate (BUG-020)
2
+
3
+ `vp-auto` enforces a **scaffold-first** rule for framework-based projects: when a task initializes a new project, the canonical scaffold command MUST run before any framework-generated files are created manually.
4
+
5
+ ## How It Works
6
+
7
+ 1. **Detection** — vp-auto detects "project setup" tasks by keywords in the task title/objective: "set up", "initialize", "create project", "scaffold", "bootstrap", "new project"
8
+ 2. **Marker check** — checks for a framework marker file (e.g. `artisan` for Laravel, `manage.py` for Django) to determine if the project is already scaffolded
9
+ 3. **Scaffold command** — if not yet scaffolded, runs the scaffold command from either:
10
+ - `~/.viepilot/stacks/{stack}/SUMMARY.md` → `## Scaffold` → `init_command:` field (takes priority)
11
+ - The built-in heuristic table in `workflows/autonomous.md`
12
+ 4. **Block list** — refuses to create framework-native files (artisan, next.config.*, manage.py, nest-cli.json, pom.xml, etc.) without prior scaffold
13
+
14
+ ## Adding a Scaffold Command to a Stack
15
+
16
+ In `~/.viepilot/stacks/{your-stack}/SUMMARY.md`, append:
17
+
18
+ ```markdown
19
+ ## Scaffold
20
+
21
+ init_command: composer create-project laravel/laravel {name}
22
+ marker_file: artisan
23
+ ```
24
+
25
+ Replace `{name}` with the project directory name placeholder — vp-auto substitutes the actual project name at runtime.
26
+
27
+ ## Built-in Supported Stacks
28
+
29
+ | Stack | Scaffold command | Marker file |
30
+ |-------|-----------------|-------------|
31
+ | laravel | `composer create-project laravel/laravel {name}` | `artisan` |
32
+ | laravel-php84 | `composer create-project laravel/laravel:^11 {name}` | `artisan` |
33
+ | nextjs | `npx create-next-app@latest {name}` | `next.config.js` |
34
+ | nextjs-tailwind-shadcn-threejs | `npx create-next-app@latest {name} --typescript --tailwind --eslint --app` | `next.config.js` |
35
+ | nestjs | `npx @nestjs/cli new {name}` | `nest-cli.json` |
36
+ | rails | `rails new {name}` | `config/application.rb` |
37
+ | django | `django-admin startproject {name} .` | `manage.py` |
38
+ | spring-boot* | `spring init --dependencies=web,data-jpa,validation {name}` | `pom.xml` |
39
+ | nuxt / vuejs* | `npx nuxi@latest init {name}` | `nuxt.config.ts` |
40
+ | react | `npx create-react-app {name}` | `src/index.js` |
41
+ | electron | `npx create-electron-app {name}` | `electron-builder.yml` |
42
+
43
+ ## Never-Handcraft Block List
44
+
45
+ The following files must never be created manually in a project setup task without first running the scaffold command:
46
+
47
+ - `artisan`, `composer.json` (Laravel)
48
+ - `next.config.js`, `next.config.ts`, `pages/_app.*`, `app/layout.*` (Next.js)
49
+ - `nest-cli.json`, `src/main.ts` + `tsconfig.json` combo (NestJS)
50
+ - `manage.py`, `wsgi.py`, `asgi.py` (Django)
51
+ - `config/application.rb`, `config/routes.rb`, `Gemfile` (Rails)
52
+ - `pom.xml` or `build.gradle` with Spring Boot starters
53
+
54
+ ## Bypassing the Gate
55
+
56
+ To override the gate (e.g. the project is already partially set up), add to the task file under `## Implementation Notes`:
57
+
58
+ ```
59
+ scaffold_gate_waiver: project already scaffolded — artisan exists at {path}
60
+ ```
61
+
62
+ Or at execution time, select "confirm project already scaffolded" at the control-point prompt.
@@ -0,0 +1,125 @@
1
+ # Skill Registry
2
+
3
+ ViePilot can discover and index skills installed across all adapter directories. The registry powers workflow skill integration — brainstorm silently applies relevant skill best practices during UI-Direction sessions, crystallize locks skill decisions, and vp-auto executes with no re-prompting.
4
+
5
+ ## Commands
6
+
7
+ | Command | Description |
8
+ |---------|-------------|
9
+ | `vp-tools scan-skills` | Scan all adapter dirs and write `~/.viepilot/skill-registry.json` |
10
+ | `vp-tools list-skills` | Display indexed skills from the registry |
11
+ | `vp-tools install-skill <source>` | Install a third-party skill *(Phase 91 — coming soon)* |
12
+
13
+ ## Extended SKILL.md Format
14
+
15
+ Third-party skills (and built-in vp-* skills) can add optional metadata sections to their `SKILL.md`:
16
+
17
+ ```markdown
18
+ ## Capabilities
19
+ - ui-generation
20
+ - component-design
21
+ - responsive-layout
22
+
23
+ ## Tags
24
+ ui, design, frontend, css, html
25
+
26
+ ## Best Practices
27
+ - Mobile-first: design breakpoints from 320px up
28
+ - Use design tokens for consistency across components
29
+ - BEM naming convention for CSS class names
30
+ ```
31
+
32
+ ### Section rules
33
+
34
+ | Section | Format | Description |
35
+ |---------|--------|-------------|
36
+ | `## Capabilities` | One capability per line (`- item`) | Machine-readable ability tags used for skill matching |
37
+ | `## Tags` | Comma-separated or one per line | Human-readable keywords for discovery |
38
+ | `## Best Practices` | One practice per line (`- item`) | Applied silently when skill is matched in brainstorm/vp-auto |
39
+
40
+ All sections are **optional** — skills without them are still indexed and available.
41
+
42
+ ### Backward compatibility
43
+
44
+ Existing `SKILL.md` files that do not contain these sections continue to work without modification. The scanner indexes them with empty `capabilities`, `tags`, and `best_practices` arrays and marks them as `(legacy — no capabilities)` in `list-skills` output.
45
+
46
+ ## Scanner
47
+
48
+ `vp-tools scan-skills` traverses the following adapter directories:
49
+
50
+ | Adapter | Skill directory |
51
+ |---------|----------------|
52
+ | Claude Code | `~/.claude/skills/` |
53
+ | Cursor | `~/.cursor/skills/` |
54
+ | Codex | `~/.codex/skills/` |
55
+ | Antigravity | `~/.gemini/antigravity/skills/` |
56
+ | GitHub Copilot | `~/.config/gh-copilot/skills/` |
57
+
58
+ Adapter directories that do not exist are silently skipped. The same skill found in multiple adapter directories is merged into a single registry entry with all adapters listed.
59
+
60
+ ## Registry Format
61
+
62
+ The registry is written to `~/.viepilot/skill-registry.json`:
63
+
64
+ ```json
65
+ {
66
+ "version": "1.0",
67
+ "last_scan": "2026-04-20T10:30:00.000Z",
68
+ "scan_paths": [
69
+ "/Users/you/.claude/skills",
70
+ "/Users/you/.cursor/skills"
71
+ ],
72
+ "skills": [
73
+ {
74
+ "id": "frontend-design",
75
+ "name": "frontend-design",
76
+ "source": null,
77
+ "version": null,
78
+ "description": "Opinionated frontend design guidance for UI-Direction sessions.",
79
+ "capabilities": ["ui-generation", "component-design", "responsive-layout"],
80
+ "tags": ["ui", "design", "frontend", "css"],
81
+ "best_practices": [
82
+ "Mobile-first: design breakpoints from 320px up",
83
+ "Use design tokens for consistency"
84
+ ],
85
+ "adapters": ["claude-code", "cursor"],
86
+ "installed_paths": {
87
+ "claude-code": "/Users/you/.claude/skills/frontend-design",
88
+ "cursor": "/Users/you/.cursor/skills/frontend-design"
89
+ }
90
+ }
91
+ ]
92
+ }
93
+ ```
94
+
95
+ ### Schema reference
96
+
97
+ | Field | Type | Description |
98
+ |-------|------|-------------|
99
+ | `id` | string | Directory name (unique per skill) |
100
+ | `name` | string | Display name (defaults to `id`) |
101
+ | `source` | string \| null | Installation source: `npm:pkg`, `github:org/repo`, `./path`, or `null` for manually placed skills |
102
+ | `version` | string \| null | Version from `skill-meta.json` (future); `null` for legacy skills |
103
+ | `description` | string | First non-heading paragraph from `SKILL.md` |
104
+ | `capabilities` | string[] | From `## Capabilities` section |
105
+ | `tags` | string[] | From `## Tags` section |
106
+ | `best_practices` | string[] | From `## Best Practices` section |
107
+ | `adapters` | string[] | Adapter IDs where this skill is installed |
108
+ | `installed_paths` | object | `{ adapterId: absolutePath }` |
109
+
110
+ ## Workflow Integration
111
+
112
+ The registry is used automatically by ViePilot workflows:
113
+
114
+ ### Brainstorm (UI-Direction)
115
+ When UI signals are detected during a brainstorm session, relevant skills (matched by `capabilities`) are silently applied — their `best_practices` are included in HTML generation without prompting. Matched skills are recorded in `notes.md` under `## skills_used`.
116
+
117
+ ### Crystallize (skill decision lock)
118
+ After the brainstorm scope is locked, crystallize presents the skills used and asks the user to confirm which are required vs optional per phase. The decision is written to `PROJECT-CONTEXT.md` under `## Skills`.
119
+
120
+ ### vp-auto (silent execution)
121
+ vp-auto reads `## Skills` from `PROJECT-CONTEXT.md` and injects skill best practices per task — no re-asking. Decisions made at crystallize time are final.
122
+
123
+ ## Refreshing the Registry
124
+
125
+ Run `vp-tools scan-skills` any time you install a new skill manually or after `vp-tools install-skill` (which runs it automatically). The registry is not auto-refreshed on session start.
@@ -6,10 +6,10 @@ const fs = require('fs');
6
6
  module.exports = {
7
7
  id: 'antigravity',
8
8
  name: 'Antigravity',
9
- skillsDir: (home) => path.join(home, '.antigravity', 'skills'),
10
- viepilotDir: (home) => path.join(home, '.antigravity', 'viepilot'),
9
+ skillsDir: (home) => path.join(home, '.gemini', 'antigravity', 'skills'),
10
+ viepilotDir: (home) => path.join(home, '.gemini', 'antigravity', 'viepilot'),
11
11
  // {envToolDir} in SKILL.md files resolves to this value at install time (ENH-035)
12
- executionContextBase: '.antigravity/viepilot',
12
+ executionContextBase: '.gemini/antigravity/viepilot',
13
13
  // Post-install hint shown in "Next actions" after viepilot install
14
14
  postInstallHint: 'Open project and run /vp-status',
15
15
  hooks: {
@@ -29,6 +29,7 @@ module.exports = {
29
29
  ],
30
30
  isAvailable: (home) => {
31
31
  const h = home || os.homedir();
32
- return fs.existsSync(path.join(h, '.antigravity'));
32
+ return fs.existsSync(path.join(h, '.gemini', 'antigravity'))
33
+ || fs.existsSync(path.join(h, '.antigravity'));
33
34
  }
34
35
  };