@vibe-agent-toolkit/vat-development-agents 0.1.22 → 0.1.23-rc.6
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/LICENSE +21 -0
- package/dist/.claude/plugins/marketplaces/vat-skills/LICENSE +21 -0
- package/dist/.claude/plugins/marketplaces/vat-skills/README.md +117 -0
- package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/.claude-plugin/plugin.json +1 -1
- package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/distribution/SKILL.md +72 -0
- package/dist/.claude/plugins/marketplaces/vat-skills/plugins/vibe-agent-toolkit/skills/vibe-agent-toolkit/SKILL.md +16 -0
- package/dist/generated/resources/skills/SKILL.d.ts +1 -0
- package/dist/generated/resources/skills/SKILL.js +8 -3
- package/dist/generated/resources/skills/vat-skills-distribution.d.ts +2 -0
- package/dist/generated/resources/skills/vat-skills-distribution.js +11 -1
- package/dist/skills/distribution/SKILL.md +72 -0
- package/dist/skills/vibe-agent-toolkit/SKILL.md +16 -0
- package/package.json +4 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Jeff Dutton
|
|
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.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Jeff Dutton
|
|
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.
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# @vibe-agent-toolkit/vat-development-agents
|
|
2
|
+
|
|
3
|
+
**VAT Development Agents** - Dogfooding the vibe-agent-toolkit
|
|
4
|
+
|
|
5
|
+
This package contains agents used for developing the Vibe Agent Toolkit itself. These agents validate schemas, generate new agents, optimize resources, and more.
|
|
6
|
+
|
|
7
|
+
## Agents
|
|
8
|
+
|
|
9
|
+
### agent-generator
|
|
10
|
+
|
|
11
|
+
**Status:** Design Complete (Phase 1.5)
|
|
12
|
+
**Purpose:** Helps users create new VAT agents through adaptive 4-phase conversation
|
|
13
|
+
|
|
14
|
+
Guides users through:
|
|
15
|
+
1. **GATHER** - Understand problem and success criteria
|
|
16
|
+
2. **ANALYZE** - Identify agent pattern, extract requirements
|
|
17
|
+
3. **DESIGN** - Choose LLM, tools, prompts, resources
|
|
18
|
+
4. **GENERATE** - Create validated agent package
|
|
19
|
+
|
|
20
|
+
[Read full design →](./agents/agent-generator/README.md)
|
|
21
|
+
|
|
22
|
+
### resource-optimizer
|
|
23
|
+
|
|
24
|
+
**Status:** Scoped (Phase 1.5)
|
|
25
|
+
**Purpose:** Analyzes agent resources for context efficiency
|
|
26
|
+
|
|
27
|
+
Identifies opportunities to improve agent resources following Anthropic's "smallest high-signal tokens" principle.
|
|
28
|
+
|
|
29
|
+
[Read scope document →](./agents/resource-optimizer/SCOPE.md)
|
|
30
|
+
|
|
31
|
+
## Package Structure
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
@vibe-agent-toolkit/vat-development-agents/
|
|
35
|
+
├── agents/
|
|
36
|
+
│ ├── agent-generator/ # Design complete
|
|
37
|
+
│ │ ├── agent.yaml # Validated manifest
|
|
38
|
+
│ │ ├── schemas/ # I/O schemas
|
|
39
|
+
│ │ ├── prompts/ # System/user prompts
|
|
40
|
+
│ │ ├── examples/ # Example usage
|
|
41
|
+
│ │ └── README.md # Full documentation
|
|
42
|
+
│ └── resource-optimizer/ # Scoped only
|
|
43
|
+
│ └── SCOPE.md # Design scope
|
|
44
|
+
└── package.json # NPM package manifest
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Installation
|
|
48
|
+
|
|
49
|
+
### As NPM Package
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
npm install @vibe-agent-toolkit/vat-development-agents
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
### Installing the Skill
|
|
56
|
+
|
|
57
|
+
This package includes a distributable Claude Code skill called `vibe-agent-toolkit` that provides guidance on using VAT for agent creation and development.
|
|
58
|
+
|
|
59
|
+
**Install from npm:**
|
|
60
|
+
```bash
|
|
61
|
+
vat skills install npm:@vibe-agent-toolkit/vat-development-agents
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
**Install from local directory (development):**
|
|
65
|
+
```bash
|
|
66
|
+
vat skills install ./packages/vat-development-agents
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
**Verify installation:**
|
|
70
|
+
```bash
|
|
71
|
+
vat skills list --installed
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
The `vibe-agent-toolkit` skill will be installed to `~/.claude/plugins/vibe-agent-toolkit/` and will appear in Claude Code after restarting or running `/reload-skills`.
|
|
75
|
+
|
|
76
|
+
**What the skill includes:**
|
|
77
|
+
- VAT overview and use cases
|
|
78
|
+
- Agent creation guide (using agent-generator)
|
|
79
|
+
- CLI workflow documentation
|
|
80
|
+
- Links to agent authoring and orchestration guides
|
|
81
|
+
- Best practices for portable agents
|
|
82
|
+
|
|
83
|
+
## Usage
|
|
84
|
+
|
|
85
|
+
### As NPM Package
|
|
86
|
+
|
|
87
|
+
```javascript
|
|
88
|
+
import agentGenerator from '@vibe-agent-toolkit/vat-development-agents/agents/agent-generator';
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### Direct Agent Access
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
# Validate agent-generator's own manifest
|
|
95
|
+
cd packages/vat-development-agents
|
|
96
|
+
bun run validate
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
## Development Status
|
|
100
|
+
|
|
101
|
+
| Agent | Phase | Status |
|
|
102
|
+
|-------|-------|--------|
|
|
103
|
+
| agent-generator | 1.5 - Design | ✅ Complete |
|
|
104
|
+
| resource-optimizer | 1.5 - Scope | ✅ Complete |
|
|
105
|
+
| schema-validator | Planned | 📋 Phase 2 |
|
|
106
|
+
| test-generator | Planned | 📋 Phase 2+ |
|
|
107
|
+
|
|
108
|
+
## Keywords
|
|
109
|
+
|
|
110
|
+
- `vat-agent` - Discoverable via `npm search vat-agent`
|
|
111
|
+
- `vibe-agent` - Alternative namespace
|
|
112
|
+
- `agent-bundle` - Contains multiple agents
|
|
113
|
+
- `development-tools` - Developer tooling
|
|
114
|
+
|
|
115
|
+
## License
|
|
116
|
+
|
|
117
|
+
MIT © VAT Team
|
|
@@ -240,6 +240,69 @@ npm publish --tag next # RC/pre-release
|
|
|
240
240
|
npm publish # stable release
|
|
241
241
|
```
|
|
242
242
|
|
|
243
|
+
## Marketplace Distribution
|
|
244
|
+
|
|
245
|
+
Marketplace distribution publishes a dedicated branch to GitHub that Claude Code users can install directly — no npm account or registry required.
|
|
246
|
+
|
|
247
|
+
### How it works
|
|
248
|
+
|
|
249
|
+
1. `vat build` compiles skills and plugin artifacts into `dist/`
|
|
250
|
+
2. `vat claude marketplace publish` pushes the `dist/.claude/` tree to a dedicated branch (e.g. `claude-marketplace`) in your GitHub repo
|
|
251
|
+
3. Users install via the slash command: `/plugin marketplace add owner/repo#claude-marketplace`
|
|
252
|
+
|
|
253
|
+
### Configuration
|
|
254
|
+
|
|
255
|
+
Add a `publish` section under your marketplace in `vibe-agent-toolkit.config.yaml`:
|
|
256
|
+
|
|
257
|
+
```yaml
|
|
258
|
+
claude:
|
|
259
|
+
marketplaces:
|
|
260
|
+
my-marketplace:
|
|
261
|
+
owner:
|
|
262
|
+
name: My Organization
|
|
263
|
+
plugins:
|
|
264
|
+
- name: my-plugin
|
|
265
|
+
description: My plugin description
|
|
266
|
+
skills: "*"
|
|
267
|
+
publish:
|
|
268
|
+
github:
|
|
269
|
+
repo: owner/repo # GitHub repo to publish to
|
|
270
|
+
branch: claude-marketplace # branch that stores the installable artifacts
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
### Publish workflow
|
|
274
|
+
|
|
275
|
+
```bash
|
|
276
|
+
vat build # build all artifacts first
|
|
277
|
+
vat claude marketplace publish # push dist/.claude/ to the publish branch
|
|
278
|
+
vat claude marketplace publish --dry-run # preview what would be published (no push)
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
### Consumer install
|
|
282
|
+
|
|
283
|
+
Once published, users install with:
|
|
284
|
+
|
|
285
|
+
```
|
|
286
|
+
/plugin marketplace add owner/repo#claude-marketplace
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
No npm, no registry, no token required. Claude Code fetches the branch directly from GitHub.
|
|
290
|
+
|
|
291
|
+
### Testing locally
|
|
292
|
+
|
|
293
|
+
After publishing, verify the marketplace works end-to-end:
|
|
294
|
+
|
|
295
|
+
```bash
|
|
296
|
+
claude plugin marketplace add owner/repo#claude-marketplace
|
|
297
|
+
claude plugin install my-plugin@my-marketplace
|
|
298
|
+
claude plugin validate ~/.claude/plugins/cache/my-marketplace/my-plugin/<version>
|
|
299
|
+
claude plugin list # verify status: enabled
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
Start a new Claude Code session to confirm skills load. See the [Marketplace Distribution Guide](https://github.com/jdutton/vibe-agent-toolkit/blob/main/docs/guides/marketplace-distribution.md#testing-your-marketplace) for the full testing checklist and known issues.
|
|
303
|
+
|
|
304
|
+
**Note (Claude Code v2.1.81):** If re-adding a marketplace with the same name as an existing one (e.g., switching from npm to GitHub source), remove the old marketplace first: `claude plugin marketplace remove <name>` then re-add. Otherwise the old source is silently reused.
|
|
305
|
+
|
|
243
306
|
## Step 5: User Install
|
|
244
307
|
|
|
245
308
|
### Recommended: npm global install (postinstall runs automatically)
|
|
@@ -330,6 +393,15 @@ TypeScript files in `scripts` are tree-shaken and compiled to standalone `.mjs`.
|
|
|
330
393
|
| Uninstall a plugin | `vat claude plugin uninstall --all` |
|
|
331
394
|
| Package for claude.ai upload | `vat skills package ./SKILL.md -o ./dist/ --target claude-web` |
|
|
332
395
|
|
|
396
|
+
## Running VAT Without Global Install
|
|
397
|
+
|
|
398
|
+
```bash
|
|
399
|
+
npx vibe-agent-toolkit <command> # npm/Node.js
|
|
400
|
+
bunx vibe-agent-toolkit <command> # Bun
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
All `vat` commands in this skill work with these alternatives.
|
|
404
|
+
|
|
333
405
|
## Future: Zero-Dependency Postinstall (Option B)
|
|
334
406
|
|
|
335
407
|
A planned improvement: `vat build` would bundle the plugin install logic into `dist/postinstall.js` — a fully self-contained script with no npm dependencies. The postinstall script would become simply `node ./dist/postinstall.js`. This eliminates `vibe-agent-toolkit` as a runtime dependency entirely, reducing install footprint for end users. Until then, Option C (runtime `vibe-agent-toolkit` dep) is the correct approach.
|
|
@@ -60,6 +60,10 @@ Four patterns cover most use cases. For full code examples, see `vibe-agent-tool
|
|
|
60
60
|
# Install VAT CLI globally
|
|
61
61
|
npm install -g vibe-agent-toolkit
|
|
62
62
|
|
|
63
|
+
# Or run without installing (works anywhere vat commands appear below)
|
|
64
|
+
npx vibe-agent-toolkit <command> # npm/Node.js
|
|
65
|
+
bunx vibe-agent-toolkit <command> # Bun
|
|
66
|
+
|
|
63
67
|
# Top-level orchestration
|
|
64
68
|
vat build # build all artifacts (skills then claude plugins)
|
|
65
69
|
vat verify # verify all artifacts (resources, skills, claude)
|
|
@@ -186,6 +190,18 @@ You've successfully adopted VAT when:
|
|
|
186
190
|
- [Runtime Adapters]()
|
|
187
191
|
- Examples: `@vibe-agent-toolkit/vat-example-cat-agents`
|
|
188
192
|
|
|
193
|
+
## Running VAT
|
|
194
|
+
|
|
195
|
+
VAT can be run without a global install:
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
vat <command> # If installed globally
|
|
199
|
+
npx vibe-agent-toolkit <command> # npm (downloads on demand)
|
|
200
|
+
bunx vibe-agent-toolkit <command> # Bun (downloads on demand)
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
All `vat` commands in this skill and sub-skills accept these alternatives.
|
|
204
|
+
|
|
189
205
|
## Getting Help
|
|
190
206
|
|
|
191
207
|
- **CLI Help:** `vat --help`, `vat skills --help`, etc.
|
|
@@ -7,7 +7,7 @@ export const meta = {
|
|
|
7
7
|
description: "Use when building, adopting, or learning vibe-agent-toolkit (VAT). Covers agent creation, CLI commands (vat skills, vat resources, vat audit, vat rag), runtime adapters, skill packaging, and resource validation. Routes to specialized sub-skills."
|
|
8
8
|
};
|
|
9
9
|
|
|
10
|
-
export const text = "\n# Vibe Agent Toolkit Skill\n\n**Vibe Agent Toolkit (VAT)** is a modular toolkit for building portable AI agents that work across\nmultiple LLM frameworks and deployment targets. Write your agent logic once as plain TypeScript,\nthen deploy it to Vercel AI SDK, LangChain, OpenAI, Claude Agent SDK, or any other runtime using\nframework adapters. No vendor lock-in.\n\n## Purpose: For Users, Not Contributors\n\n- **This skill** = How to USE VAT to build agents\n- **\`vibe-agent-toolkit:debugging\`** = When VAT itself behaves unexpectedly or you need to test a fix\n- **Root CLAUDE.md** = How to DEVELOP the VAT codebase itself\n\n## When to Use VAT\n\n**VAT is great for:** Multi-framework projects, reusable agent libraries, testing across LLM\nproviders, complex multi-agent orchestration, human-in-the-loop workflows.\n\n**VAT may not be needed for:** Simple one-off scripts where the framework is already decided,\nnon-TypeScript/JavaScript projects, or cases where you need deep framework-specific features.\n\n## Skill Routing Table\n\n| If you\'re working on... | Use this skill |\n|---|---|\n| Writing or structuring a \`SKILL.md\` file | \`vibe-agent-toolkit:authoring\` |\n| Agent archetypes, orchestration patterns, result envelopes | \`vibe-agent-toolkit:authoring\` |\n| \`packagingOptions\` (linkFollowDepth, excludeReferencesFromBundle) | \`vibe-agent-toolkit:authoring\` |\n| Resource collections, frontmatter schema validation | \`vibe-agent-toolkit:resources\` |\n| \`vat resources validate\`, collection config | \`vibe-agent-toolkit:resources\` |\n| Setting up \`vat build\` + \`vat claude build\` for a project | \`vibe-agent-toolkit:distribution\` |\n| Configuring \`claude:\` section in vibe-agent-toolkit.config.yaml | \`vibe-agent-toolkit:distribution\` |\n| npm publishing with plugin postinstall | \`vibe-agent-toolkit:distribution\` |\n| \`vat build\` / \`vat verify\` orchestration | \`vibe-agent-toolkit:distribution\` |\n| \`--target claude-web\` ZIP format | \`vibe-agent-toolkit:distribution\` |\n| Install/uninstall methods, enterprise deployment, Desktop vs CLI paths | \`vibe-agent-toolkit:install\` |\n| \`vat audit\`, \`--compat\`, CI validation | \`vibe-agent-toolkit:audit\` |\n| \`vat claude org\`, Admin API, org users/cost/usage/skills, ANTHROPIC_ADMIN_API_KEY | \`vibe-agent-toolkit:org-admin\` |\n| VAT behaves unexpectedly, debugging VAT, testing local VAT changes, VAT_ROOT_DIR | \`vibe-agent-toolkit:debugging\` |\n\n## Agent Archetypes (Quick Reference)\n\nFour patterns cover most use cases. For full code examples, see \`vibe-agent-toolkit:authoring\`.\n\n| Archetype | When to Use |\n|---|---|\n| **Pure Function Tool** | Stateless validation, transformation, computation — no LLM needed |\n| **One-Shot LLM Analyzer** | Single LLM call for analysis, classification, or generation |\n| **Conversational Assistant** | Multi-turn dialogue with session state across turns |\n| **External Event Integrator** | Waiting for human approval, webhooks, or third-party APIs |\n\n## Core CLI Commands\n\n\`\`\`bash\n# Install VAT CLI globally\nnpm install -g vibe-agent-toolkit\n\n# Top-level orchestration\nvat build # build all artifacts (skills then claude plugins)\nvat verify # verify all artifacts (resources, skills, claude)\n\n# Claude plugin commands\nvat claude build # generate plugin artifacts from built skills\nvat claude verify # validate plugin artifacts\n\n# Skills\nvat skills list # list skills in current project\nvat skills list --user # list user-installed skills\nvat skills install npm:@org/my-skills # install from npm (routes through plugin system)\nvat skills build # build portable skills only\nvat skills validate # validate skill quality\n\n# Resources\nvat resources validate # validate collections (reads config)\nvat resources validate docs/ --frontmatter-schema schema.json\n\n# Audit\nvat audit # audit current directory recursively\nvat audit --user # audit entire Claude installation\nvat audit ./plugins/ --compat # check surface compatibility\n\n# RAG\nvat rag index docs/ # index markdown into vector DB\nvat rag query \"my question\" --limit 5 # semantic search\n\n# Get help for any command\nvat --help\nvat skills --help\n\`\`\`\n\n## agent-generator: Creating New Agents\n\nThe **agent-generator** is a built-in meta-agent that guides you through designing\nhigh-quality agents via a 4-phase workflow:\n\n1. **GATHER** — Understand your intent and goals\n2. **ANALYZE** — Identify agent pattern and requirements\n3. **DESIGN** — Make architecture decisions (LLM, tools, prompts)\n4. **GENERATE** — Create validated agent package\n\nMinimum input needed:\n\`\`\`json\n{\n \"agentPurpose\": \"Review PRs for security issues\",\n \"successCriteria\": \"Catches 100% of critical vulnerabilities\"\n}\n\`\`\`\n\nThe generator produces: \`agent.yaml\`, \`prompts/system.md\`, \`prompts/user.md\`,\n\`schemas/input.schema.json\`, \`schemas/output.schema.json\`, and \`README.md\`.\n\n**Tips for better results:**\n- Be specific about success criteria (\"Under 30s, zero false negatives\") not vague (\"fast enough\")\n- Name the tools the agent needs upfront (file readers, APIs, etc.)\n- Describe domain context (OWASP Top 10, company coding standards, etc.)\n\n## Packaging Markdown for Reuse\n\nVAT\'s resource compiler transforms markdown files into type-safe TypeScript modules,\nenabling prompt libraries, RAG knowledge bases, and shared content across projects.\n\n\`\`\`bash\nnpm install -D @vibe-agent-toolkit/resource-compiler\nnpx vat-compile-resources compile resources/ generated/resources/\n\`\`\`\n\n\`\`\`typescript\nimport * as Doc from \'./generated/resources/doc.js\';\n\nDoc.meta.title; // type-safe frontmatter\nDoc.fragments.introduction.text; // H2 section content\nDoc.text; // full markdown\n\`\`\`\n\nUse cases: agent prompt libraries, RAG knowledge bases packaged as npm modules,\nmulti-project content sharing with versioning.\n\n## Common Workflows\n\n**Create a new agent:**\n\`\`\`bash\n# Use agent-generator interactively, then:\nvat agent import my-skill/SKILL.md # import to VAT format\nvat skills validate # check quality\nvat skills build # package for distribution\n\`\`\`\n\n**Install and use a community skill:**\n\`\`\`bash\nvat skills install npm:@vibe-agent-toolkit/vat-cat-agents\nvat skills list --user\n# Plugin-aware packages register in Claude\'s plugin system\n# Skills are invoked as /plugin-name:skill-name in Claude Code\n\`\`\`\n\n**Build and publish your own skill package:**\n\`\`\`bash\n# Configure vat.skills in package.json + claude: in vibe-agent-toolkit.config.yaml, then:\nvat build # builds skills + claude plugin artifacts\nvat verify # validates everything\nnpm publish # publishes to npm (postinstall registers the plugin)\n# Users install with: vat skills install npm:@myorg/my-skills\n\`\`\`\n\n## Success Criteria\n\nYou\'ve successfully adopted VAT when:\n- Agents have clear input/output schemas (Zod-validated)\n- Errors are handled as data (result envelopes), never thrown\n- Tests cover success and error paths without real API calls (mock mode)\n- Agents work across multiple runtimes via adapters\n- Multi-agent pipelines compose via \`andThen()\` / \`match()\` helpers\n\n## Documentation Index\n\n- [Getting Started Guide](../../../../docs/getting-started.md)\n- [Agent Authoring Guide](../../../../docs/agent-authoring.md) — patterns and code examples\n- [Orchestration Guide](../../../../docs/orchestration.md) — multi-agent workflows\n- [RAG Usage Guide](../../../../docs/guides/rag-usage-guide.md)\n- [Resource Compiler Guide](../../../../docs/guides/resource-compiler/compiling-markdown-to-typescript.md)\n- [Runtime Adapters](../../../../docs/adding-runtime-adapters.md)\n- Examples: \`@vibe-agent-toolkit/vat-example-cat-agents\`\n\n## Getting Help\n\n- **CLI Help:** \`vat --help\`, \`vat skills --help\`, etc.\n- **Examples:** \`packages/vat-example-cat-agents/\`\n- **GitHub Issues:** Report bugs or ask questions\n\nHappy agent building!\n";
|
|
10
|
+
export const text = "\n# Vibe Agent Toolkit Skill\n\n**Vibe Agent Toolkit (VAT)** is a modular toolkit for building portable AI agents that work across\nmultiple LLM frameworks and deployment targets. Write your agent logic once as plain TypeScript,\nthen deploy it to Vercel AI SDK, LangChain, OpenAI, Claude Agent SDK, or any other runtime using\nframework adapters. No vendor lock-in.\n\n## Purpose: For Users, Not Contributors\n\n- **This skill** = How to USE VAT to build agents\n- **\`vibe-agent-toolkit:debugging\`** = When VAT itself behaves unexpectedly or you need to test a fix\n- **Root CLAUDE.md** = How to DEVELOP the VAT codebase itself\n\n## When to Use VAT\n\n**VAT is great for:** Multi-framework projects, reusable agent libraries, testing across LLM\nproviders, complex multi-agent orchestration, human-in-the-loop workflows.\n\n**VAT may not be needed for:** Simple one-off scripts where the framework is already decided,\nnon-TypeScript/JavaScript projects, or cases where you need deep framework-specific features.\n\n## Skill Routing Table\n\n| If you\'re working on... | Use this skill |\n|---|---|\n| Writing or structuring a \`SKILL.md\` file | \`vibe-agent-toolkit:authoring\` |\n| Agent archetypes, orchestration patterns, result envelopes | \`vibe-agent-toolkit:authoring\` |\n| \`packagingOptions\` (linkFollowDepth, excludeReferencesFromBundle) | \`vibe-agent-toolkit:authoring\` |\n| Resource collections, frontmatter schema validation | \`vibe-agent-toolkit:resources\` |\n| \`vat resources validate\`, collection config | \`vibe-agent-toolkit:resources\` |\n| Setting up \`vat build\` + \`vat claude build\` for a project | \`vibe-agent-toolkit:distribution\` |\n| Configuring \`claude:\` section in vibe-agent-toolkit.config.yaml | \`vibe-agent-toolkit:distribution\` |\n| npm publishing with plugin postinstall | \`vibe-agent-toolkit:distribution\` |\n| \`vat build\` / \`vat verify\` orchestration | \`vibe-agent-toolkit:distribution\` |\n| \`--target claude-web\` ZIP format | \`vibe-agent-toolkit:distribution\` |\n| Install/uninstall methods, enterprise deployment, Desktop vs CLI paths | \`vibe-agent-toolkit:install\` |\n| \`vat audit\`, \`--compat\`, CI validation | \`vibe-agent-toolkit:audit\` |\n| \`vat claude org\`, Admin API, org users/cost/usage/skills, ANTHROPIC_ADMIN_API_KEY | \`vibe-agent-toolkit:org-admin\` |\n| VAT behaves unexpectedly, debugging VAT, testing local VAT changes, VAT_ROOT_DIR | \`vibe-agent-toolkit:debugging\` |\n\n## Agent Archetypes (Quick Reference)\n\nFour patterns cover most use cases. For full code examples, see \`vibe-agent-toolkit:authoring\`.\n\n| Archetype | When to Use |\n|---|---|\n| **Pure Function Tool** | Stateless validation, transformation, computation — no LLM needed |\n| **One-Shot LLM Analyzer** | Single LLM call for analysis, classification, or generation |\n| **Conversational Assistant** | Multi-turn dialogue with session state across turns |\n| **External Event Integrator** | Waiting for human approval, webhooks, or third-party APIs |\n\n## Core CLI Commands\n\n\`\`\`bash\n# Install VAT CLI globally\nnpm install -g vibe-agent-toolkit\n\n# Or run without installing (works anywhere vat commands appear below)\nnpx vibe-agent-toolkit <command> # npm/Node.js\nbunx vibe-agent-toolkit <command> # Bun\n\n# Top-level orchestration\nvat build # build all artifacts (skills then claude plugins)\nvat verify # verify all artifacts (resources, skills, claude)\n\n# Claude plugin commands\nvat claude build # generate plugin artifacts from built skills\nvat claude verify # validate plugin artifacts\n\n# Skills\nvat skills list # list skills in current project\nvat skills list --user # list user-installed skills\nvat skills install npm:@org/my-skills # install from npm (routes through plugin system)\nvat skills build # build portable skills only\nvat skills validate # validate skill quality\n\n# Resources\nvat resources validate # validate collections (reads config)\nvat resources validate docs/ --frontmatter-schema schema.json\n\n# Audit\nvat audit # audit current directory recursively\nvat audit --user # audit entire Claude installation\nvat audit ./plugins/ --compat # check surface compatibility\n\n# RAG\nvat rag index docs/ # index markdown into vector DB\nvat rag query \"my question\" --limit 5 # semantic search\n\n# Get help for any command\nvat --help\nvat skills --help\n\`\`\`\n\n## agent-generator: Creating New Agents\n\nThe **agent-generator** is a built-in meta-agent that guides you through designing\nhigh-quality agents via a 4-phase workflow:\n\n1. **GATHER** — Understand your intent and goals\n2. **ANALYZE** — Identify agent pattern and requirements\n3. **DESIGN** — Make architecture decisions (LLM, tools, prompts)\n4. **GENERATE** — Create validated agent package\n\nMinimum input needed:\n\`\`\`json\n{\n \"agentPurpose\": \"Review PRs for security issues\",\n \"successCriteria\": \"Catches 100% of critical vulnerabilities\"\n}\n\`\`\`\n\nThe generator produces: \`agent.yaml\`, \`prompts/system.md\`, \`prompts/user.md\`,\n\`schemas/input.schema.json\`, \`schemas/output.schema.json\`, and \`README.md\`.\n\n**Tips for better results:**\n- Be specific about success criteria (\"Under 30s, zero false negatives\") not vague (\"fast enough\")\n- Name the tools the agent needs upfront (file readers, APIs, etc.)\n- Describe domain context (OWASP Top 10, company coding standards, etc.)\n\n## Packaging Markdown for Reuse\n\nVAT\'s resource compiler transforms markdown files into type-safe TypeScript modules,\nenabling prompt libraries, RAG knowledge bases, and shared content across projects.\n\n\`\`\`bash\nnpm install -D @vibe-agent-toolkit/resource-compiler\nnpx vat-compile-resources compile resources/ generated/resources/\n\`\`\`\n\n\`\`\`typescript\nimport * as Doc from \'./generated/resources/doc.js\';\n\nDoc.meta.title; // type-safe frontmatter\nDoc.fragments.introduction.text; // H2 section content\nDoc.text; // full markdown\n\`\`\`\n\nUse cases: agent prompt libraries, RAG knowledge bases packaged as npm modules,\nmulti-project content sharing with versioning.\n\n## Common Workflows\n\n**Create a new agent:**\n\`\`\`bash\n# Use agent-generator interactively, then:\nvat agent import my-skill/SKILL.md # import to VAT format\nvat skills validate # check quality\nvat skills build # package for distribution\n\`\`\`\n\n**Install and use a community skill:**\n\`\`\`bash\nvat skills install npm:@vibe-agent-toolkit/vat-cat-agents\nvat skills list --user\n# Plugin-aware packages register in Claude\'s plugin system\n# Skills are invoked as /plugin-name:skill-name in Claude Code\n\`\`\`\n\n**Build and publish your own skill package:**\n\`\`\`bash\n# Configure vat.skills in package.json + claude: in vibe-agent-toolkit.config.yaml, then:\nvat build # builds skills + claude plugin artifacts\nvat verify # validates everything\nnpm publish # publishes to npm (postinstall registers the plugin)\n# Users install with: vat skills install npm:@myorg/my-skills\n\`\`\`\n\n## Success Criteria\n\nYou\'ve successfully adopted VAT when:\n- Agents have clear input/output schemas (Zod-validated)\n- Errors are handled as data (result envelopes), never thrown\n- Tests cover success and error paths without real API calls (mock mode)\n- Agents work across multiple runtimes via adapters\n- Multi-agent pipelines compose via \`andThen()\` / \`match()\` helpers\n\n## Documentation Index\n\n- [Getting Started Guide](../../../../docs/getting-started.md)\n- [Agent Authoring Guide](../../../../docs/agent-authoring.md) — patterns and code examples\n- [Orchestration Guide](../../../../docs/orchestration.md) — multi-agent workflows\n- [RAG Usage Guide](../../../../docs/guides/rag-usage-guide.md)\n- [Resource Compiler Guide](../../../../docs/guides/resource-compiler/compiling-markdown-to-typescript.md)\n- [Runtime Adapters](../../../../docs/adding-runtime-adapters.md)\n- Examples: \`@vibe-agent-toolkit/vat-example-cat-agents\`\n\n## Running VAT\n\nVAT can be run without a global install:\n\n\`\`\`bash\nvat <command> # If installed globally\nnpx vibe-agent-toolkit <command> # npm (downloads on demand)\nbunx vibe-agent-toolkit <command> # Bun (downloads on demand)\n\`\`\`\n\nAll \`vat\` commands in this skill and sub-skills accept these alternatives.\n\n## Getting Help\n\n- **CLI Help:** \`vat --help\`, \`vat skills --help\`, etc.\n- **Examples:** \`packages/vat-example-cat-agents/\`\n- **GitHub Issues:** Report bugs or ask questions\n\nHappy agent building!\n";
|
|
11
11
|
|
|
12
12
|
export const fragments = {
|
|
13
13
|
purposeForUsersNotContributors: {
|
|
@@ -32,8 +32,8 @@ export const fragments = {
|
|
|
32
32
|
},
|
|
33
33
|
coreCliCommands: {
|
|
34
34
|
header: "## Core CLI Commands",
|
|
35
|
-
body: "\`\`\`bash\n# Install VAT CLI globally\nnpm install -g vibe-agent-toolkit\n\n# Top-level orchestration\nvat build # build all artifacts (skills then claude plugins)\nvat verify # verify all artifacts (resources, skills, claude)\n\n# Claude plugin commands\nvat claude build # generate plugin artifacts from built skills\nvat claude verify # validate plugin artifacts\n\n# Skills\nvat skills list # list skills in current project\nvat skills list --user # list user-installed skills\nvat skills install npm:@org/my-skills # install from npm (routes through plugin system)\nvat skills build # build portable skills only\nvat skills validate # validate skill quality\n\n# Resources\nvat resources validate # validate collections (reads config)\nvat resources validate docs/ --frontmatter-schema schema.json\n\n# Audit\nvat audit # audit current directory recursively\nvat audit --user # audit entire Claude installation\nvat audit ./plugins/ --compat # check surface compatibility\n\n# RAG\nvat rag index docs/ # index markdown into vector DB\nvat rag query \"my question\" --limit 5 # semantic search\n\n# Get help for any command\nvat --help\nvat skills --help\n\`\`\`",
|
|
36
|
-
text: "## Core CLI Commands\n\n\`\`\`bash\n# Install VAT CLI globally\nnpm install -g vibe-agent-toolkit\n\n# Top-level orchestration\nvat build # build all artifacts (skills then claude plugins)\nvat verify # verify all artifacts (resources, skills, claude)\n\n# Claude plugin commands\nvat claude build # generate plugin artifacts from built skills\nvat claude verify # validate plugin artifacts\n\n# Skills\nvat skills list # list skills in current project\nvat skills list --user # list user-installed skills\nvat skills install npm:@org/my-skills # install from npm (routes through plugin system)\nvat skills build # build portable skills only\nvat skills validate # validate skill quality\n\n# Resources\nvat resources validate # validate collections (reads config)\nvat resources validate docs/ --frontmatter-schema schema.json\n\n# Audit\nvat audit # audit current directory recursively\nvat audit --user # audit entire Claude installation\nvat audit ./plugins/ --compat # check surface compatibility\n\n# RAG\nvat rag index docs/ # index markdown into vector DB\nvat rag query \"my question\" --limit 5 # semantic search\n\n# Get help for any command\nvat --help\nvat skills --help\n\`\`\`"
|
|
35
|
+
body: "\`\`\`bash\n# Install VAT CLI globally\nnpm install -g vibe-agent-toolkit\n\n# Or run without installing (works anywhere vat commands appear below)\nnpx vibe-agent-toolkit <command> # npm/Node.js\nbunx vibe-agent-toolkit <command> # Bun\n\n# Top-level orchestration\nvat build # build all artifacts (skills then claude plugins)\nvat verify # verify all artifacts (resources, skills, claude)\n\n# Claude plugin commands\nvat claude build # generate plugin artifacts from built skills\nvat claude verify # validate plugin artifacts\n\n# Skills\nvat skills list # list skills in current project\nvat skills list --user # list user-installed skills\nvat skills install npm:@org/my-skills # install from npm (routes through plugin system)\nvat skills build # build portable skills only\nvat skills validate # validate skill quality\n\n# Resources\nvat resources validate # validate collections (reads config)\nvat resources validate docs/ --frontmatter-schema schema.json\n\n# Audit\nvat audit # audit current directory recursively\nvat audit --user # audit entire Claude installation\nvat audit ./plugins/ --compat # check surface compatibility\n\n# RAG\nvat rag index docs/ # index markdown into vector DB\nvat rag query \"my question\" --limit 5 # semantic search\n\n# Get help for any command\nvat --help\nvat skills --help\n\`\`\`",
|
|
36
|
+
text: "## Core CLI Commands\n\n\`\`\`bash\n# Install VAT CLI globally\nnpm install -g vibe-agent-toolkit\n\n# Or run without installing (works anywhere vat commands appear below)\nnpx vibe-agent-toolkit <command> # npm/Node.js\nbunx vibe-agent-toolkit <command> # Bun\n\n# Top-level orchestration\nvat build # build all artifacts (skills then claude plugins)\nvat verify # verify all artifacts (resources, skills, claude)\n\n# Claude plugin commands\nvat claude build # generate plugin artifacts from built skills\nvat claude verify # validate plugin artifacts\n\n# Skills\nvat skills list # list skills in current project\nvat skills list --user # list user-installed skills\nvat skills install npm:@org/my-skills # install from npm (routes through plugin system)\nvat skills build # build portable skills only\nvat skills validate # validate skill quality\n\n# Resources\nvat resources validate # validate collections (reads config)\nvat resources validate docs/ --frontmatter-schema schema.json\n\n# Audit\nvat audit # audit current directory recursively\nvat audit --user # audit entire Claude installation\nvat audit ./plugins/ --compat # check surface compatibility\n\n# RAG\nvat rag index docs/ # index markdown into vector DB\nvat rag query \"my question\" --limit 5 # semantic search\n\n# Get help for any command\nvat --help\nvat skills --help\n\`\`\`"
|
|
37
37
|
},
|
|
38
38
|
agentGeneratorCreatingNewAgents: {
|
|
39
39
|
header: "## agent-generator: Creating New Agents",
|
|
@@ -60,6 +60,11 @@ export const fragments = {
|
|
|
60
60
|
body: "- [Getting Started Guide](../../../../docs/getting-started.md)\n- [Agent Authoring Guide](../../../../docs/agent-authoring.md) — patterns and code examples\n- [Orchestration Guide](../../../../docs/orchestration.md) — multi-agent workflows\n- [RAG Usage Guide](../../../../docs/guides/rag-usage-guide.md)\n- [Resource Compiler Guide](../../../../docs/guides/resource-compiler/compiling-markdown-to-typescript.md)\n- [Runtime Adapters](../../../../docs/adding-runtime-adapters.md)\n- Examples: \`@vibe-agent-toolkit/vat-example-cat-agents\`",
|
|
61
61
|
text: "## Documentation Index\n\n- [Getting Started Guide](../../../../docs/getting-started.md)\n- [Agent Authoring Guide](../../../../docs/agent-authoring.md) — patterns and code examples\n- [Orchestration Guide](../../../../docs/orchestration.md) — multi-agent workflows\n- [RAG Usage Guide](../../../../docs/guides/rag-usage-guide.md)\n- [Resource Compiler Guide](../../../../docs/guides/resource-compiler/compiling-markdown-to-typescript.md)\n- [Runtime Adapters](../../../../docs/adding-runtime-adapters.md)\n- Examples: \`@vibe-agent-toolkit/vat-example-cat-agents\`"
|
|
62
62
|
},
|
|
63
|
+
runningVat: {
|
|
64
|
+
header: "## Running VAT",
|
|
65
|
+
body: "VAT can be run without a global install:\n\n\`\`\`bash\nvat <command> # If installed globally\nnpx vibe-agent-toolkit <command> # npm (downloads on demand)\nbunx vibe-agent-toolkit <command> # Bun (downloads on demand)\n\`\`\`\n\nAll \`vat\` commands in this skill and sub-skills accept these alternatives.",
|
|
66
|
+
text: "## Running VAT\n\nVAT can be run without a global install:\n\n\`\`\`bash\nvat <command> # If installed globally\nnpx vibe-agent-toolkit <command> # npm (downloads on demand)\nbunx vibe-agent-toolkit <command> # Bun (downloads on demand)\n\`\`\`\n\nAll \`vat\` commands in this skill and sub-skills accept these alternatives."
|
|
67
|
+
},
|
|
63
68
|
gettingHelp: {
|
|
64
69
|
header: "## Getting Help",
|
|
65
70
|
body: "- **CLI Help:** \`vat --help\`, \`vat skills --help\`, etc.\n- **Examples:** \`packages/vat-example-cat-agents/\`\n- **GitHub Issues:** Report bugs or ask questions\n\nHappy agent building!",
|
|
@@ -24,10 +24,12 @@ export const fragments: {
|
|
|
24
24
|
readonly step2VibeAgentToolkitconfigyaml: Fragment;
|
|
25
25
|
readonly step3Build: Fragment;
|
|
26
26
|
readonly step4Publish: Fragment;
|
|
27
|
+
readonly marketplaceDistribution: Fragment;
|
|
27
28
|
readonly step5UserInstall: Fragment;
|
|
28
29
|
readonly managedSettingsjsonValidationEnterprise: Fragment;
|
|
29
30
|
readonly -TargetClaudeWebZipUpload: Fragment;
|
|
30
31
|
readonly quickReference: Fragment;
|
|
32
|
+
readonly runningVatWithoutGlobalInstall: Fragment;
|
|
31
33
|
readonly futureZeroDependencyPostinstallOptionB: Fragment;
|
|
32
34
|
};
|
|
33
35
|
|
|
@@ -7,7 +7,7 @@ export const meta = {
|
|
|
7
7
|
description: "Use when setting up vat build, configuring plugin distribution for the Claude ecosystem (marketplace, plugins, managed settings), npm publishing with postinstall hooks, or vat verify orchestration. Covers the full pipeline from skill source to installed plugin."
|
|
8
8
|
};
|
|
9
9
|
|
|
10
|
-
export const text = "\n# VAT Distribution: Build, Publish & Install\n\n## Scope\n\nThis skill covers the **file-based install method for Claude Code CLI** (\`~/.claude/plugins/\`).\nThis is the only install method VAT currently supports.\n\nFor the full install landscape — Claude Desktop paths, enterprise CI deployment,\nAnthropic Cloud org management, MDM integration, and the \`vat plugins uninstall\`\ndesign — see [Install & Uninstall Architecture](vat-install-architecture.md).\n\n## Overview\n\nVAT distributes skills as **Claude plugins** via npm packages. The pipeline:\n\n1. \`vat build\` compiles SKILL.md sources into plugin artifacts\n2. \`npm publish\` pushes the package to a registry\n3. \`npm install\` triggers a postinstall hook that registers the plugin in Claude Code\'s plugin system\n\nSkills installed this way appear in Claude Code as \`/plugin-name:skill-name\`.\n\n## Project Structure\n\n\`\`\`\nmy-project/\n├── package.json ← vat.skills + postinstall hook + publishConfig\n├── vibe-agent-toolkit.config.yaml ← skills: + claude: config\n├── resources/\n│ └── skills/\n│ └── SKILL.md\n└── dist/ ← generated by vat build\n ├── skills/my-skill/ ← packaged skill\n └── .claude/plugins/marketplaces/\n └── my-marketplace/plugins/my-plugin/\n ├── .claude-plugin/plugin.json\n └── skills/my-skill/SKILL.md\n\`\`\`\n\n## Step 1: package.json Configuration\n\n\`\`\`json\n{\n \"name\": \"@myorg/my-skills\",\n \"version\": \"1.0.0\",\n \"vat\": {\n \"version\": \"1.0\",\n \"skills\": [\"my-skill\"]\n },\n \"dependencies\": {\n \"vibe-agent-toolkit\": \"latest\"\n },\n \"scripts\": {\n \"build:vat\": \"vat build\",\n \"postinstall\": \"vat claude plugin install --npm-postinstall 2>/dev/null || exit 0\"\n },\n \"files\": [\"dist\", \"README.md\"],\n \"publishConfig\": {\n \"registry\": \"https://registry.npmjs.org\"\n }\n}\n\`\`\`\n\n**\`vibe-agent-toolkit\` must be in \`dependencies\` (not \`devDependencies\`).** npm adds all \`bin\` entries from runtime dependencies to \`./node_modules/.bin/\` and puts that on PATH when running lifecycle scripts. This is how \`vat\` is available during your postinstall without being globally installed. If it is in \`devDependencies\`, npm will not install it on the user\'s machine and the postinstall will fail with \"command not found\".\n\nThe \`vat.skills\` array contains skill name strings for npm discoverability. Skill source paths and packaging config live in \`vibe-agent-toolkit.config.yaml\` (see Step 2).\n\nFor private GitHub Packages registry:\n\`\`\`json\n\"publishConfig\": {\n \"registry\": \"https://npm.pkg.github.com\",\n \"access\": \"restricted\"\n}\n\`\`\`\n\nUsers (or IT) installing from GitHub Packages need \`.npmrc\` configured with the scope registry and a read-only token:\n\`\`\`\n@myorg:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}\n\`\`\`\n\nIT deploying to managed machines should pre-configure \`.npmrc\` at the system or user level before running install commands. End users do not need to understand npm or the registry — IT handles it once.\n\n## Handling Plugin Renames: vat.replaces\n\n> **Use this only when renaming a plugin, merging plugins, or cleaning up legacy flat-skill installs. Normal upgrades (same plugin name, same skills) do NOT need \`vat.replaces\` — the installer already overwrites the plugin directory on every install.**\n\n### The problem: silent stale skills\n\nWhen you rename a plugin or reorganize skills across packages, the old registration remains in Claude Code. Claude Code **does not warn you** when two plugins provide conflicting skill names — the first-registered (stale) skill silently wins. Users continue loading old content from the renamed plugin unless the old registration is explicitly removed.\n\nThis is the scenario where \`vat.replaces\` is needed:\n- Plugin renamed: \`old-plugin-name\` → \`new-plugin-name\`\n- Two old plugins merged into one new plugin\n- Skills previously installed to \`~/.claude/skills/<name>\` (legacy pre-0.1.20 flat install) now delivered via the plugin tree\n\n### How it works\n\nWhen a VAT package is installed (via postinstall hook or \`--dev\`), the installer reads \`vat.replaces\` from \`package.json\` and — **before** installing the new plugin:\n\n1. For each name in \`replaces.plugins\`: uninstalls \`<name>@<marketplace>\` — removes plugin directory, cache entry, registry entry, and \`settings.json\` entry\n2. For each name in \`replaces.flatSkills\`: deletes \`~/.claude/skills/<name>\` — removes legacy pre-0.1.20 flat installs\n\nBoth operations are idempotent — \"not found\" is handled gracefully.\n\n### Schema\n\n\`\`\`json\n\"vat\": {\n \"version\": \"1.0\",\n \"skills\": [\"authoring\", \"audit\"],\n \"replaces\": {\n \"plugins\": [\"my-old-plugin-name\"],\n \"flatSkills\": [\"my-old-skill\", \"another-old-skill\"]\n }\n}\n\`\`\`\n\nBoth \`plugins\` and \`flatSkills\` are optional arrays. The entire \`replaces\` key is optional — omit it when there is nothing to clean up.\n\n### Real example: vat-development-agents 0.1.21\n\nThis package (\`vat-development-agents\`) renamed its plugin from \`vat-development-agents\` to \`vibe-agent-toolkit\` in v0.1.21. Without \`vat.replaces\`, users who had already installed v0.1.20 would have both \`vat-development-agents@vat-skills\` and \`vibe-agent-toolkit@vat-skills\` registered — Claude Code would serve stale skill content from the old plugin.\n\nThe fix in \`package.json\`:\n\n\`\`\`json\n\"vat\": {\n \"version\": \"1.0\",\n \"skills\": [\"vibe-agent-toolkit\", \"resources\", \"distribution\", \"authoring\", \"audit\", \"debugging\", \"install\"],\n \"replaces\": {\n \"plugins\": [\"vat-development-agents\"],\n \"flatSkills\": [\"vibe-agent-toolkit\", \"resources\"]\n }\n}\n\`\`\`\n\n- \`plugins\`: removes the old plugin registration (same marketplace, old plugin name)\n- \`flatSkills\`: removes legacy \`~/.claude/skills/vibe-agent-toolkit\` and \`~/.claude/skills/resources\` entries from users who installed before 0.1.20 switched to the plugin tree\n\n### Non-obvious gotchas\n\n**1. Plugin names in \`replaces.plugins\` have NO \`@marketplace\`**\n\nThe format is just the plugin name — e.g. \`\"vat-development-agents\"\` — NOT \`\"vat-development-agents@vat-skills\"\`. The installer infers the marketplace from the current package\'s dist tree. Using \`@marketplace\` syntax here would be wrong.\n\n**2. \`replaces.plugins\` is for old plugin registrations, not for skills that moved between plugins**\n\nIf a skill moved from \`plugin-a\` to \`plugin-b\` within the same marketplace, list \`\"plugin-a\"\` in \`replaces.plugins\` to clean up the entire old plugin. You do not manage individual skills — you manage plugins.\n\n**3. \`replaces.flatSkills\` is ONLY for the legacy \`~/.claude/skills/\` location**\n\nThis is specifically for skills that were previously installed as flat files to \`~/.claude/skills/<name>\` (pre-plugin-tree, before v0.1.20). Skills within the plugin tree (under \`~/.claude/plugins/\`) are handled via \`replaces.plugins\`. Do not mix them up.\n\n**4. Normal upgrades need nothing**\n\nIf you publish a new version of the same package with the same plugin name, the installer overwrites the plugin directory automatically. \`vat.replaces\` is only for the case where the old name is different from the new name.\n\n**5. The symptom is subtle and delayed**\n\nYou will not see an error. Claude Code simply loads the first-registered skill with a given name. If the stale plugin is registered first (alphabetically or by install order), your new content is invisible until you remove the old registration.\n\n## Step 2: vibe-agent-toolkit.config.yaml\n\n\`\`\`yaml\nversion: 1\n\nskills:\n include:\n - \"resources/skills/**/SKILL.md\"\n\nclaude:\n marketplaces:\n my-marketplace: # org/publisher identity\n owner:\n name: My Organization\n plugins:\n - name: my-plugin # installable unit\n description: My plugin description\n skills: \"*\" # all discovered skills\n\`\`\`\n\nThe \`skills:\` section discovers SKILL.md files via include/exclude globs. The \`claude:\` section defines how skills are packaged into plugins. Each marketplace has \`owner\` and \`plugins\` fields (strict schema — no extra fields).\n\n**Naming convention:** marketplace = org identity (e.g. \`acme\`), plugin = this package\n(e.g. \`acme-tools\`). Registers as \`my-plugin@my-marketplace\` in Claude\'s plugin registry.\n\n### Multiple skills in one package\n\nList all skills in \`vat.skills\` for npm discoverability:\n\n\`\`\`json\n\"vat\": {\n \"version\": \"1.0\",\n \"skills\": [\"my-linting\", \"my-testing\"]\n}\n\`\`\`\n\nUse a selector in the plugin config to include matching skills:\n\n\`\`\`yaml\nplugins:\n - name: my-plugin\n description: Linting and testing skills\n skills:\n - \"my-linting\"\n - \"my-testing\"\n\`\`\`\n\nOr use \`\"*\"\` to include all discovered skills in the plugin.\n\n## Step 3: Build\n\n\`\`\`bash\nvat build # skills phase then claude phase\nvat verify # validates resources + skills + claude artifacts\n\`\`\`\n\n### What vat build does\n\nTwo phases, run in dependency order:\n\n1. **\`vat skills build\`** — reads \`vibe-agent-toolkit.config.yaml skills:\` section, discovers SKILL.md files via include/exclude globs, compiles each into \`dist/skills/<name>/\`\n2. **\`vat claude plugin build\`** — reads \`vibe-agent-toolkit.config.yaml claude:\` section, wraps built skills into \`dist/.claude/plugins/marketplaces/<mp>/plugins/<plugin>/\` structure with \`.claude-plugin/plugin.json\`. Cleans stale output before each build.\n\nIndividual commands still work:\n\`\`\`bash\nvat skills build # skills phase only\nvat claude plugin build # claude plugin phase only (requires skills already built)\n\`\`\`\n\n## Step 4: Publish\n\n\`\`\`bash\nnpm publish --tag next # RC/pre-release\nnpm publish # stable release\n\`\`\`\n\n## Step 5: User Install\n\n### Recommended: npm global install (postinstall runs automatically)\n\n\`\`\`bash\nnpm install -g @myorg/my-skills\n\`\`\`\n\nThe postinstall hook fires automatically and registers the plugin in Claude. This is the correct path for IT-managed deployments — no other tools required on the user\'s machine.\n\n### Developer/IT one-off install via npx\n\n\`\`\`bash\nnpx vibe-agent-toolkit claude plugin install npm:@myorg/my-skills\n\`\`\`\n\nDownloads and runs VAT via npx to install a package without a global install. Useful for CI, scripting, or testing from a developer machine. Requires the npm scope registry to be configured (\`.npmrc\`) if installing from a private registry.\n\n### How plugin installation works\n\nWhen \`npm install\` runs the postinstall hook (\`vat claude plugin install --npm-postinstall\`):\n\n- VAT detects \`dist/.claude/plugins/marketplaces/\` directory in the installed package\n- Copies the plugin tree to Claude\'s plugin directory (dumb recursive copy)\n- Writes to these locations:\n 1. \`~/.claude/plugins/marketplaces/<marketplace>/plugins/<plugin>/\` — plugin files\n 2. \`~/.claude/plugins/known_marketplaces.json\` — marketplace registry\n 3. \`~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/\` — version cache\n 4. \`~/.claude/plugins/installed_plugins.json\` — installation record\n 5. \`~/.claude/settings.json\` \`enabledPlugins\` — activates the plugin\n\nIf no \`dist/.claude/plugins/marketplaces/\` directory exists (package wasn\'t built before publish): a guidance message is emitted and the hook exits 0. The publisher must run \`vat build\` and re-publish.\n\nSkills are then available in Claude Code as \`/plugin-name:skill-name\`.\n\n## managed-settings.json Validation (Enterprise)\n\n\`\`\`yaml\nclaude:\n managedSettings: managed-settings.json\n\`\`\`\n\n\`vat verify\` validates this file against the ManagedSettings schema. Catches typos and schema errors before deployment. Does NOT deploy the file — deployment is a separate concern.\n\n## --target claude-web (ZIP Upload)\n\nFor uploading skills directly to \`claude.ai/settings/capabilities\`:\n\n\`\`\`bash\nvat skills package ./SKILL.md -o ./dist/ --target claude-web\n\`\`\`\n\nProduces a ZIP:\n\`\`\`\nmy-skill.zip\n└── my-skill/\n ├── SKILL.md # skill definition (required)\n ├── scripts/ # executable code (.mjs, .py, .sh) — optional\n ├── references/ # markdown reference material — optional\n └── assets/ # static data, templates, config — optional\n\`\`\`\n\nConfigure source path mappings in \`vibe-agent-toolkit.config.yaml\`:\n\`\`\`yaml\nskills:\n include:\n - \"skills/**/SKILL.md\"\n config:\n my-skill:\n claudeWebTarget:\n scripts: [\"./src/helpers/**/*.ts\"]\n assets: [\"./assets/**\"]\n\`\`\`\n\nTypeScript files in \`scripts\` are tree-shaken and compiled to standalone \`.mjs\`.\n\n## Quick Reference\n\n| Task | Command |\n|---|---|\n| Build everything | \`vat build\` |\n| Verify everything | \`vat verify\` |\n| Build skills only | \`vat skills build\` |\n| Build claude plugin artifacts only | \`vat claude plugin build\` |\n| Install via npm (end user) | \`npm install -g @org/pkg\` |\n| Install via npx (developer/IT) | \`npx vibe-agent-toolkit claude plugin install npm:@org/pkg\` |\n| List installed plugins | \`vat claude plugin list\` |\n| Uninstall a plugin | \`vat claude plugin uninstall --all\` |\n| Package for claude.ai upload | \`vat skills package ./SKILL.md -o ./dist/ --target claude-web\` |\n\n## Future: Zero-Dependency Postinstall (Option B)\n\nA planned improvement: \`vat build\` would bundle the plugin install logic into \`dist/postinstall.js\` — a fully self-contained script with no npm dependencies. The postinstall script would become simply \`node ./dist/postinstall.js\`. This eliminates \`vibe-agent-toolkit\` as a runtime dependency entirely, reducing install footprint for end users. Until then, Option C (runtime \`vibe-agent-toolkit\` dep) is the correct approach.\n";
|
|
10
|
+
export const text = "\n# VAT Distribution: Build, Publish & Install\n\n## Scope\n\nThis skill covers the **file-based install method for Claude Code CLI** (\`~/.claude/plugins/\`).\nThis is the only install method VAT currently supports.\n\nFor the full install landscape — Claude Desktop paths, enterprise CI deployment,\nAnthropic Cloud org management, MDM integration, and the \`vat plugins uninstall\`\ndesign — see [Install & Uninstall Architecture](vat-install-architecture.md).\n\n## Overview\n\nVAT distributes skills as **Claude plugins** via npm packages. The pipeline:\n\n1. \`vat build\` compiles SKILL.md sources into plugin artifacts\n2. \`npm publish\` pushes the package to a registry\n3. \`npm install\` triggers a postinstall hook that registers the plugin in Claude Code\'s plugin system\n\nSkills installed this way appear in Claude Code as \`/plugin-name:skill-name\`.\n\n## Project Structure\n\n\`\`\`\nmy-project/\n├── package.json ← vat.skills + postinstall hook + publishConfig\n├── vibe-agent-toolkit.config.yaml ← skills: + claude: config\n├── resources/\n│ └── skills/\n│ └── SKILL.md\n└── dist/ ← generated by vat build\n ├── skills/my-skill/ ← packaged skill\n └── .claude/plugins/marketplaces/\n └── my-marketplace/plugins/my-plugin/\n ├── .claude-plugin/plugin.json\n └── skills/my-skill/SKILL.md\n\`\`\`\n\n## Step 1: package.json Configuration\n\n\`\`\`json\n{\n \"name\": \"@myorg/my-skills\",\n \"version\": \"1.0.0\",\n \"vat\": {\n \"version\": \"1.0\",\n \"skills\": [\"my-skill\"]\n },\n \"dependencies\": {\n \"vibe-agent-toolkit\": \"latest\"\n },\n \"scripts\": {\n \"build:vat\": \"vat build\",\n \"postinstall\": \"vat claude plugin install --npm-postinstall 2>/dev/null || exit 0\"\n },\n \"files\": [\"dist\", \"README.md\"],\n \"publishConfig\": {\n \"registry\": \"https://registry.npmjs.org\"\n }\n}\n\`\`\`\n\n**\`vibe-agent-toolkit\` must be in \`dependencies\` (not \`devDependencies\`).** npm adds all \`bin\` entries from runtime dependencies to \`./node_modules/.bin/\` and puts that on PATH when running lifecycle scripts. This is how \`vat\` is available during your postinstall without being globally installed. If it is in \`devDependencies\`, npm will not install it on the user\'s machine and the postinstall will fail with \"command not found\".\n\nThe \`vat.skills\` array contains skill name strings for npm discoverability. Skill source paths and packaging config live in \`vibe-agent-toolkit.config.yaml\` (see Step 2).\n\nFor private GitHub Packages registry:\n\`\`\`json\n\"publishConfig\": {\n \"registry\": \"https://npm.pkg.github.com\",\n \"access\": \"restricted\"\n}\n\`\`\`\n\nUsers (or IT) installing from GitHub Packages need \`.npmrc\` configured with the scope registry and a read-only token:\n\`\`\`\n@myorg:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}\n\`\`\`\n\nIT deploying to managed machines should pre-configure \`.npmrc\` at the system or user level before running install commands. End users do not need to understand npm or the registry — IT handles it once.\n\n## Handling Plugin Renames: vat.replaces\n\n> **Use this only when renaming a plugin, merging plugins, or cleaning up legacy flat-skill installs. Normal upgrades (same plugin name, same skills) do NOT need \`vat.replaces\` — the installer already overwrites the plugin directory on every install.**\n\n### The problem: silent stale skills\n\nWhen you rename a plugin or reorganize skills across packages, the old registration remains in Claude Code. Claude Code **does not warn you** when two plugins provide conflicting skill names — the first-registered (stale) skill silently wins. Users continue loading old content from the renamed plugin unless the old registration is explicitly removed.\n\nThis is the scenario where \`vat.replaces\` is needed:\n- Plugin renamed: \`old-plugin-name\` → \`new-plugin-name\`\n- Two old plugins merged into one new plugin\n- Skills previously installed to \`~/.claude/skills/<name>\` (legacy pre-0.1.20 flat install) now delivered via the plugin tree\n\n### How it works\n\nWhen a VAT package is installed (via postinstall hook or \`--dev\`), the installer reads \`vat.replaces\` from \`package.json\` and — **before** installing the new plugin:\n\n1. For each name in \`replaces.plugins\`: uninstalls \`<name>@<marketplace>\` — removes plugin directory, cache entry, registry entry, and \`settings.json\` entry\n2. For each name in \`replaces.flatSkills\`: deletes \`~/.claude/skills/<name>\` — removes legacy pre-0.1.20 flat installs\n\nBoth operations are idempotent — \"not found\" is handled gracefully.\n\n### Schema\n\n\`\`\`json\n\"vat\": {\n \"version\": \"1.0\",\n \"skills\": [\"authoring\", \"audit\"],\n \"replaces\": {\n \"plugins\": [\"my-old-plugin-name\"],\n \"flatSkills\": [\"my-old-skill\", \"another-old-skill\"]\n }\n}\n\`\`\`\n\nBoth \`plugins\` and \`flatSkills\` are optional arrays. The entire \`replaces\` key is optional — omit it when there is nothing to clean up.\n\n### Real example: vat-development-agents 0.1.21\n\nThis package (\`vat-development-agents\`) renamed its plugin from \`vat-development-agents\` to \`vibe-agent-toolkit\` in v0.1.21. Without \`vat.replaces\`, users who had already installed v0.1.20 would have both \`vat-development-agents@vat-skills\` and \`vibe-agent-toolkit@vat-skills\` registered — Claude Code would serve stale skill content from the old plugin.\n\nThe fix in \`package.json\`:\n\n\`\`\`json\n\"vat\": {\n \"version\": \"1.0\",\n \"skills\": [\"vibe-agent-toolkit\", \"resources\", \"distribution\", \"authoring\", \"audit\", \"debugging\", \"install\"],\n \"replaces\": {\n \"plugins\": [\"vat-development-agents\"],\n \"flatSkills\": [\"vibe-agent-toolkit\", \"resources\"]\n }\n}\n\`\`\`\n\n- \`plugins\`: removes the old plugin registration (same marketplace, old plugin name)\n- \`flatSkills\`: removes legacy \`~/.claude/skills/vibe-agent-toolkit\` and \`~/.claude/skills/resources\` entries from users who installed before 0.1.20 switched to the plugin tree\n\n### Non-obvious gotchas\n\n**1. Plugin names in \`replaces.plugins\` have NO \`@marketplace\`**\n\nThe format is just the plugin name — e.g. \`\"vat-development-agents\"\` — NOT \`\"vat-development-agents@vat-skills\"\`. The installer infers the marketplace from the current package\'s dist tree. Using \`@marketplace\` syntax here would be wrong.\n\n**2. \`replaces.plugins\` is for old plugin registrations, not for skills that moved between plugins**\n\nIf a skill moved from \`plugin-a\` to \`plugin-b\` within the same marketplace, list \`\"plugin-a\"\` in \`replaces.plugins\` to clean up the entire old plugin. You do not manage individual skills — you manage plugins.\n\n**3. \`replaces.flatSkills\` is ONLY for the legacy \`~/.claude/skills/\` location**\n\nThis is specifically for skills that were previously installed as flat files to \`~/.claude/skills/<name>\` (pre-plugin-tree, before v0.1.20). Skills within the plugin tree (under \`~/.claude/plugins/\`) are handled via \`replaces.plugins\`. Do not mix them up.\n\n**4. Normal upgrades need nothing**\n\nIf you publish a new version of the same package with the same plugin name, the installer overwrites the plugin directory automatically. \`vat.replaces\` is only for the case where the old name is different from the new name.\n\n**5. The symptom is subtle and delayed**\n\nYou will not see an error. Claude Code simply loads the first-registered skill with a given name. If the stale plugin is registered first (alphabetically or by install order), your new content is invisible until you remove the old registration.\n\n## Step 2: vibe-agent-toolkit.config.yaml\n\n\`\`\`yaml\nversion: 1\n\nskills:\n include:\n - \"resources/skills/**/SKILL.md\"\n\nclaude:\n marketplaces:\n my-marketplace: # org/publisher identity\n owner:\n name: My Organization\n plugins:\n - name: my-plugin # installable unit\n description: My plugin description\n skills: \"*\" # all discovered skills\n\`\`\`\n\nThe \`skills:\` section discovers SKILL.md files via include/exclude globs. The \`claude:\` section defines how skills are packaged into plugins. Each marketplace has \`owner\` and \`plugins\` fields (strict schema — no extra fields).\n\n**Naming convention:** marketplace = org identity (e.g. \`acme\`), plugin = this package\n(e.g. \`acme-tools\`). Registers as \`my-plugin@my-marketplace\` in Claude\'s plugin registry.\n\n### Multiple skills in one package\n\nList all skills in \`vat.skills\` for npm discoverability:\n\n\`\`\`json\n\"vat\": {\n \"version\": \"1.0\",\n \"skills\": [\"my-linting\", \"my-testing\"]\n}\n\`\`\`\n\nUse a selector in the plugin config to include matching skills:\n\n\`\`\`yaml\nplugins:\n - name: my-plugin\n description: Linting and testing skills\n skills:\n - \"my-linting\"\n - \"my-testing\"\n\`\`\`\n\nOr use \`\"*\"\` to include all discovered skills in the plugin.\n\n## Step 3: Build\n\n\`\`\`bash\nvat build # skills phase then claude phase\nvat verify # validates resources + skills + claude artifacts\n\`\`\`\n\n### What vat build does\n\nTwo phases, run in dependency order:\n\n1. **\`vat skills build\`** — reads \`vibe-agent-toolkit.config.yaml skills:\` section, discovers SKILL.md files via include/exclude globs, compiles each into \`dist/skills/<name>/\`\n2. **\`vat claude plugin build\`** — reads \`vibe-agent-toolkit.config.yaml claude:\` section, wraps built skills into \`dist/.claude/plugins/marketplaces/<mp>/plugins/<plugin>/\` structure with \`.claude-plugin/plugin.json\`. Cleans stale output before each build.\n\nIndividual commands still work:\n\`\`\`bash\nvat skills build # skills phase only\nvat claude plugin build # claude plugin phase only (requires skills already built)\n\`\`\`\n\n## Step 4: Publish\n\n\`\`\`bash\nnpm publish --tag next # RC/pre-release\nnpm publish # stable release\n\`\`\`\n\n## Marketplace Distribution\n\nMarketplace distribution publishes a dedicated branch to GitHub that Claude Code users can install directly — no npm account or registry required.\n\n### How it works\n\n1. \`vat build\` compiles skills and plugin artifacts into \`dist/\`\n2. \`vat claude marketplace publish\` pushes the \`dist/.claude/\` tree to a dedicated branch (e.g. \`claude-marketplace\`) in your GitHub repo\n3. Users install via the slash command: \`/plugin marketplace add owner/repo#claude-marketplace\`\n\n### Configuration\n\nAdd a \`publish\` section under your marketplace in \`vibe-agent-toolkit.config.yaml\`:\n\n\`\`\`yaml\nclaude:\n marketplaces:\n my-marketplace:\n owner:\n name: My Organization\n plugins:\n - name: my-plugin\n description: My plugin description\n skills: \"*\"\n publish:\n github:\n repo: owner/repo # GitHub repo to publish to\n branch: claude-marketplace # branch that stores the installable artifacts\n\`\`\`\n\n### Publish workflow\n\n\`\`\`bash\nvat build # build all artifacts first\nvat claude marketplace publish # push dist/.claude/ to the publish branch\nvat claude marketplace publish --dry-run # preview what would be published (no push)\n\`\`\`\n\n### Consumer install\n\nOnce published, users install with:\n\n\`\`\`\n/plugin marketplace add owner/repo#claude-marketplace\n\`\`\`\n\nNo npm, no registry, no token required. Claude Code fetches the branch directly from GitHub.\n\n### Testing locally\n\nAfter publishing, verify the marketplace works end-to-end:\n\n\`\`\`bash\nclaude plugin marketplace add owner/repo#claude-marketplace\nclaude plugin install my-plugin@my-marketplace\nclaude plugin validate ~/.claude/plugins/cache/my-marketplace/my-plugin/<version>\nclaude plugin list # verify status: enabled\n\`\`\`\n\nStart a new Claude Code session to confirm skills load. See the [Marketplace Distribution Guide](https://github.com/jdutton/vibe-agent-toolkit/blob/main/docs/guides/marketplace-distribution.md#testing-your-marketplace) for the full testing checklist and known issues.\n\n**Note (Claude Code v2.1.81):** If re-adding a marketplace with the same name as an existing one (e.g., switching from npm to GitHub source), remove the old marketplace first: \`claude plugin marketplace remove <name>\` then re-add. Otherwise the old source is silently reused.\n\n## Step 5: User Install\n\n### Recommended: npm global install (postinstall runs automatically)\n\n\`\`\`bash\nnpm install -g @myorg/my-skills\n\`\`\`\n\nThe postinstall hook fires automatically and registers the plugin in Claude. This is the correct path for IT-managed deployments — no other tools required on the user\'s machine.\n\n### Developer/IT one-off install via npx\n\n\`\`\`bash\nnpx vibe-agent-toolkit claude plugin install npm:@myorg/my-skills\n\`\`\`\n\nDownloads and runs VAT via npx to install a package without a global install. Useful for CI, scripting, or testing from a developer machine. Requires the npm scope registry to be configured (\`.npmrc\`) if installing from a private registry.\n\n### How plugin installation works\n\nWhen \`npm install\` runs the postinstall hook (\`vat claude plugin install --npm-postinstall\`):\n\n- VAT detects \`dist/.claude/plugins/marketplaces/\` directory in the installed package\n- Copies the plugin tree to Claude\'s plugin directory (dumb recursive copy)\n- Writes to these locations:\n 1. \`~/.claude/plugins/marketplaces/<marketplace>/plugins/<plugin>/\` — plugin files\n 2. \`~/.claude/plugins/known_marketplaces.json\` — marketplace registry\n 3. \`~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/\` — version cache\n 4. \`~/.claude/plugins/installed_plugins.json\` — installation record\n 5. \`~/.claude/settings.json\` \`enabledPlugins\` — activates the plugin\n\nIf no \`dist/.claude/plugins/marketplaces/\` directory exists (package wasn\'t built before publish): a guidance message is emitted and the hook exits 0. The publisher must run \`vat build\` and re-publish.\n\nSkills are then available in Claude Code as \`/plugin-name:skill-name\`.\n\n## managed-settings.json Validation (Enterprise)\n\n\`\`\`yaml\nclaude:\n managedSettings: managed-settings.json\n\`\`\`\n\n\`vat verify\` validates this file against the ManagedSettings schema. Catches typos and schema errors before deployment. Does NOT deploy the file — deployment is a separate concern.\n\n## --target claude-web (ZIP Upload)\n\nFor uploading skills directly to \`claude.ai/settings/capabilities\`:\n\n\`\`\`bash\nvat skills package ./SKILL.md -o ./dist/ --target claude-web\n\`\`\`\n\nProduces a ZIP:\n\`\`\`\nmy-skill.zip\n└── my-skill/\n ├── SKILL.md # skill definition (required)\n ├── scripts/ # executable code (.mjs, .py, .sh) — optional\n ├── references/ # markdown reference material — optional\n └── assets/ # static data, templates, config — optional\n\`\`\`\n\nConfigure source path mappings in \`vibe-agent-toolkit.config.yaml\`:\n\`\`\`yaml\nskills:\n include:\n - \"skills/**/SKILL.md\"\n config:\n my-skill:\n claudeWebTarget:\n scripts: [\"./src/helpers/**/*.ts\"]\n assets: [\"./assets/**\"]\n\`\`\`\n\nTypeScript files in \`scripts\` are tree-shaken and compiled to standalone \`.mjs\`.\n\n## Quick Reference\n\n| Task | Command |\n|---|---|\n| Build everything | \`vat build\` |\n| Verify everything | \`vat verify\` |\n| Build skills only | \`vat skills build\` |\n| Build claude plugin artifacts only | \`vat claude plugin build\` |\n| Install via npm (end user) | \`npm install -g @org/pkg\` |\n| Install via npx (developer/IT) | \`npx vibe-agent-toolkit claude plugin install npm:@org/pkg\` |\n| List installed plugins | \`vat claude plugin list\` |\n| Uninstall a plugin | \`vat claude plugin uninstall --all\` |\n| Package for claude.ai upload | \`vat skills package ./SKILL.md -o ./dist/ --target claude-web\` |\n\n## Running VAT Without Global Install\n\n\`\`\`bash\nnpx vibe-agent-toolkit <command> # npm/Node.js\nbunx vibe-agent-toolkit <command> # Bun\n\`\`\`\n\nAll \`vat\` commands in this skill work with these alternatives.\n\n## Future: Zero-Dependency Postinstall (Option B)\n\nA planned improvement: \`vat build\` would bundle the plugin install logic into \`dist/postinstall.js\` — a fully self-contained script with no npm dependencies. The postinstall script would become simply \`node ./dist/postinstall.js\`. This eliminates \`vibe-agent-toolkit\` as a runtime dependency entirely, reducing install footprint for end users. Until then, Option C (runtime \`vibe-agent-toolkit\` dep) is the correct approach.\n";
|
|
11
11
|
|
|
12
12
|
export const fragments = {
|
|
13
13
|
scope: {
|
|
@@ -50,6 +50,11 @@ export const fragments = {
|
|
|
50
50
|
body: "\`\`\`bash\nnpm publish --tag next # RC/pre-release\nnpm publish # stable release\n\`\`\`",
|
|
51
51
|
text: "## Step 4: Publish\n\n\`\`\`bash\nnpm publish --tag next # RC/pre-release\nnpm publish # stable release\n\`\`\`"
|
|
52
52
|
},
|
|
53
|
+
marketplaceDistribution: {
|
|
54
|
+
header: "## Marketplace Distribution",
|
|
55
|
+
body: "Marketplace distribution publishes a dedicated branch to GitHub that Claude Code users can install directly — no npm account or registry required.\n\n### How it works\n\n1. \`vat build\` compiles skills and plugin artifacts into \`dist/\`\n2. \`vat claude marketplace publish\` pushes the \`dist/.claude/\` tree to a dedicated branch (e.g. \`claude-marketplace\`) in your GitHub repo\n3. Users install via the slash command: \`/plugin marketplace add owner/repo#claude-marketplace\`\n\n### Configuration\n\nAdd a \`publish\` section under your marketplace in \`vibe-agent-toolkit.config.yaml\`:\n\n\`\`\`yaml\nclaude:\n marketplaces:\n my-marketplace:\n owner:\n name: My Organization\n plugins:\n - name: my-plugin\n description: My plugin description\n skills: \"*\"\n publish:\n github:\n repo: owner/repo # GitHub repo to publish to\n branch: claude-marketplace # branch that stores the installable artifacts\n\`\`\`\n\n### Publish workflow\n\n\`\`\`bash\nvat build # build all artifacts first\nvat claude marketplace publish # push dist/.claude/ to the publish branch\nvat claude marketplace publish --dry-run # preview what would be published (no push)\n\`\`\`\n\n### Consumer install\n\nOnce published, users install with:\n\n\`\`\`\n/plugin marketplace add owner/repo#claude-marketplace\n\`\`\`\n\nNo npm, no registry, no token required. Claude Code fetches the branch directly from GitHub.\n\n### Testing locally\n\nAfter publishing, verify the marketplace works end-to-end:\n\n\`\`\`bash\nclaude plugin marketplace add owner/repo#claude-marketplace\nclaude plugin install my-plugin@my-marketplace\nclaude plugin validate ~/.claude/plugins/cache/my-marketplace/my-plugin/<version>\nclaude plugin list # verify status: enabled\n\`\`\`\n\nStart a new Claude Code session to confirm skills load. See the [Marketplace Distribution Guide](https://github.com/jdutton/vibe-agent-toolkit/blob/main/docs/guides/marketplace-distribution.md#testing-your-marketplace) for the full testing checklist and known issues.\n\n**Note (Claude Code v2.1.81):** If re-adding a marketplace with the same name as an existing one (e.g., switching from npm to GitHub source), remove the old marketplace first: \`claude plugin marketplace remove <name>\` then re-add. Otherwise the old source is silently reused.",
|
|
56
|
+
text: "## Marketplace Distribution\n\nMarketplace distribution publishes a dedicated branch to GitHub that Claude Code users can install directly — no npm account or registry required.\n\n### How it works\n\n1. \`vat build\` compiles skills and plugin artifacts into \`dist/\`\n2. \`vat claude marketplace publish\` pushes the \`dist/.claude/\` tree to a dedicated branch (e.g. \`claude-marketplace\`) in your GitHub repo\n3. Users install via the slash command: \`/plugin marketplace add owner/repo#claude-marketplace\`\n\n### Configuration\n\nAdd a \`publish\` section under your marketplace in \`vibe-agent-toolkit.config.yaml\`:\n\n\`\`\`yaml\nclaude:\n marketplaces:\n my-marketplace:\n owner:\n name: My Organization\n plugins:\n - name: my-plugin\n description: My plugin description\n skills: \"*\"\n publish:\n github:\n repo: owner/repo # GitHub repo to publish to\n branch: claude-marketplace # branch that stores the installable artifacts\n\`\`\`\n\n### Publish workflow\n\n\`\`\`bash\nvat build # build all artifacts first\nvat claude marketplace publish # push dist/.claude/ to the publish branch\nvat claude marketplace publish --dry-run # preview what would be published (no push)\n\`\`\`\n\n### Consumer install\n\nOnce published, users install with:\n\n\`\`\`\n/plugin marketplace add owner/repo#claude-marketplace\n\`\`\`\n\nNo npm, no registry, no token required. Claude Code fetches the branch directly from GitHub.\n\n### Testing locally\n\nAfter publishing, verify the marketplace works end-to-end:\n\n\`\`\`bash\nclaude plugin marketplace add owner/repo#claude-marketplace\nclaude plugin install my-plugin@my-marketplace\nclaude plugin validate ~/.claude/plugins/cache/my-marketplace/my-plugin/<version>\nclaude plugin list # verify status: enabled\n\`\`\`\n\nStart a new Claude Code session to confirm skills load. See the [Marketplace Distribution Guide](https://github.com/jdutton/vibe-agent-toolkit/blob/main/docs/guides/marketplace-distribution.md#testing-your-marketplace) for the full testing checklist and known issues.\n\n**Note (Claude Code v2.1.81):** If re-adding a marketplace with the same name as an existing one (e.g., switching from npm to GitHub source), remove the old marketplace first: \`claude plugin marketplace remove <name>\` then re-add. Otherwise the old source is silently reused."
|
|
57
|
+
},
|
|
53
58
|
step5UserInstall: {
|
|
54
59
|
header: "## Step 5: User Install",
|
|
55
60
|
body: "### Recommended: npm global install (postinstall runs automatically)\n\n\`\`\`bash\nnpm install -g @myorg/my-skills\n\`\`\`\n\nThe postinstall hook fires automatically and registers the plugin in Claude. This is the correct path for IT-managed deployments — no other tools required on the user\'s machine.\n\n### Developer/IT one-off install via npx\n\n\`\`\`bash\nnpx vibe-agent-toolkit claude plugin install npm:@myorg/my-skills\n\`\`\`\n\nDownloads and runs VAT via npx to install a package without a global install. Useful for CI, scripting, or testing from a developer machine. Requires the npm scope registry to be configured (\`.npmrc\`) if installing from a private registry.\n\n### How plugin installation works\n\nWhen \`npm install\` runs the postinstall hook (\`vat claude plugin install --npm-postinstall\`):\n\n- VAT detects \`dist/.claude/plugins/marketplaces/\` directory in the installed package\n- Copies the plugin tree to Claude\'s plugin directory (dumb recursive copy)\n- Writes to these locations:\n 1. \`~/.claude/plugins/marketplaces/<marketplace>/plugins/<plugin>/\` — plugin files\n 2. \`~/.claude/plugins/known_marketplaces.json\` — marketplace registry\n 3. \`~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/\` — version cache\n 4. \`~/.claude/plugins/installed_plugins.json\` — installation record\n 5. \`~/.claude/settings.json\` \`enabledPlugins\` — activates the plugin\n\nIf no \`dist/.claude/plugins/marketplaces/\` directory exists (package wasn\'t built before publish): a guidance message is emitted and the hook exits 0. The publisher must run \`vat build\` and re-publish.\n\nSkills are then available in Claude Code as \`/plugin-name:skill-name\`.",
|
|
@@ -70,6 +75,11 @@ export const fragments = {
|
|
|
70
75
|
body: "| Task | Command |\n|---|---|\n| Build everything | \`vat build\` |\n| Verify everything | \`vat verify\` |\n| Build skills only | \`vat skills build\` |\n| Build claude plugin artifacts only | \`vat claude plugin build\` |\n| Install via npm (end user) | \`npm install -g @org/pkg\` |\n| Install via npx (developer/IT) | \`npx vibe-agent-toolkit claude plugin install npm:@org/pkg\` |\n| List installed plugins | \`vat claude plugin list\` |\n| Uninstall a plugin | \`vat claude plugin uninstall --all\` |\n| Package for claude.ai upload | \`vat skills package ./SKILL.md -o ./dist/ --target claude-web\` |",
|
|
71
76
|
text: "## Quick Reference\n\n| Task | Command |\n|---|---|\n| Build everything | \`vat build\` |\n| Verify everything | \`vat verify\` |\n| Build skills only | \`vat skills build\` |\n| Build claude plugin artifacts only | \`vat claude plugin build\` |\n| Install via npm (end user) | \`npm install -g @org/pkg\` |\n| Install via npx (developer/IT) | \`npx vibe-agent-toolkit claude plugin install npm:@org/pkg\` |\n| List installed plugins | \`vat claude plugin list\` |\n| Uninstall a plugin | \`vat claude plugin uninstall --all\` |\n| Package for claude.ai upload | \`vat skills package ./SKILL.md -o ./dist/ --target claude-web\` |"
|
|
72
77
|
},
|
|
78
|
+
runningVatWithoutGlobalInstall: {
|
|
79
|
+
header: "## Running VAT Without Global Install",
|
|
80
|
+
body: "\`\`\`bash\nnpx vibe-agent-toolkit <command> # npm/Node.js\nbunx vibe-agent-toolkit <command> # Bun\n\`\`\`\n\nAll \`vat\` commands in this skill work with these alternatives.",
|
|
81
|
+
text: "## Running VAT Without Global Install\n\n\`\`\`bash\nnpx vibe-agent-toolkit <command> # npm/Node.js\nbunx vibe-agent-toolkit <command> # Bun\n\`\`\`\n\nAll \`vat\` commands in this skill work with these alternatives."
|
|
82
|
+
},
|
|
73
83
|
futureZeroDependencyPostinstallOptionB: {
|
|
74
84
|
header: "## Future: Zero-Dependency Postinstall (Option B)",
|
|
75
85
|
body: "A planned improvement: \`vat build\` would bundle the plugin install logic into \`dist/postinstall.js\` — a fully self-contained script with no npm dependencies. The postinstall script would become simply \`node ./dist/postinstall.js\`. This eliminates \`vibe-agent-toolkit\` as a runtime dependency entirely, reducing install footprint for end users. Until then, Option C (runtime \`vibe-agent-toolkit\` dep) is the correct approach.",
|
|
@@ -240,6 +240,69 @@ npm publish --tag next # RC/pre-release
|
|
|
240
240
|
npm publish # stable release
|
|
241
241
|
```
|
|
242
242
|
|
|
243
|
+
## Marketplace Distribution
|
|
244
|
+
|
|
245
|
+
Marketplace distribution publishes a dedicated branch to GitHub that Claude Code users can install directly — no npm account or registry required.
|
|
246
|
+
|
|
247
|
+
### How it works
|
|
248
|
+
|
|
249
|
+
1. `vat build` compiles skills and plugin artifacts into `dist/`
|
|
250
|
+
2. `vat claude marketplace publish` pushes the `dist/.claude/` tree to a dedicated branch (e.g. `claude-marketplace`) in your GitHub repo
|
|
251
|
+
3. Users install via the slash command: `/plugin marketplace add owner/repo#claude-marketplace`
|
|
252
|
+
|
|
253
|
+
### Configuration
|
|
254
|
+
|
|
255
|
+
Add a `publish` section under your marketplace in `vibe-agent-toolkit.config.yaml`:
|
|
256
|
+
|
|
257
|
+
```yaml
|
|
258
|
+
claude:
|
|
259
|
+
marketplaces:
|
|
260
|
+
my-marketplace:
|
|
261
|
+
owner:
|
|
262
|
+
name: My Organization
|
|
263
|
+
plugins:
|
|
264
|
+
- name: my-plugin
|
|
265
|
+
description: My plugin description
|
|
266
|
+
skills: "*"
|
|
267
|
+
publish:
|
|
268
|
+
github:
|
|
269
|
+
repo: owner/repo # GitHub repo to publish to
|
|
270
|
+
branch: claude-marketplace # branch that stores the installable artifacts
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
### Publish workflow
|
|
274
|
+
|
|
275
|
+
```bash
|
|
276
|
+
vat build # build all artifacts first
|
|
277
|
+
vat claude marketplace publish # push dist/.claude/ to the publish branch
|
|
278
|
+
vat claude marketplace publish --dry-run # preview what would be published (no push)
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
### Consumer install
|
|
282
|
+
|
|
283
|
+
Once published, users install with:
|
|
284
|
+
|
|
285
|
+
```
|
|
286
|
+
/plugin marketplace add owner/repo#claude-marketplace
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
No npm, no registry, no token required. Claude Code fetches the branch directly from GitHub.
|
|
290
|
+
|
|
291
|
+
### Testing locally
|
|
292
|
+
|
|
293
|
+
After publishing, verify the marketplace works end-to-end:
|
|
294
|
+
|
|
295
|
+
```bash
|
|
296
|
+
claude plugin marketplace add owner/repo#claude-marketplace
|
|
297
|
+
claude plugin install my-plugin@my-marketplace
|
|
298
|
+
claude plugin validate ~/.claude/plugins/cache/my-marketplace/my-plugin/<version>
|
|
299
|
+
claude plugin list # verify status: enabled
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
Start a new Claude Code session to confirm skills load. See the [Marketplace Distribution Guide](https://github.com/jdutton/vibe-agent-toolkit/blob/main/docs/guides/marketplace-distribution.md#testing-your-marketplace) for the full testing checklist and known issues.
|
|
303
|
+
|
|
304
|
+
**Note (Claude Code v2.1.81):** If re-adding a marketplace with the same name as an existing one (e.g., switching from npm to GitHub source), remove the old marketplace first: `claude plugin marketplace remove <name>` then re-add. Otherwise the old source is silently reused.
|
|
305
|
+
|
|
243
306
|
## Step 5: User Install
|
|
244
307
|
|
|
245
308
|
### Recommended: npm global install (postinstall runs automatically)
|
|
@@ -330,6 +393,15 @@ TypeScript files in `scripts` are tree-shaken and compiled to standalone `.mjs`.
|
|
|
330
393
|
| Uninstall a plugin | `vat claude plugin uninstall --all` |
|
|
331
394
|
| Package for claude.ai upload | `vat skills package ./SKILL.md -o ./dist/ --target claude-web` |
|
|
332
395
|
|
|
396
|
+
## Running VAT Without Global Install
|
|
397
|
+
|
|
398
|
+
```bash
|
|
399
|
+
npx vibe-agent-toolkit <command> # npm/Node.js
|
|
400
|
+
bunx vibe-agent-toolkit <command> # Bun
|
|
401
|
+
```
|
|
402
|
+
|
|
403
|
+
All `vat` commands in this skill work with these alternatives.
|
|
404
|
+
|
|
333
405
|
## Future: Zero-Dependency Postinstall (Option B)
|
|
334
406
|
|
|
335
407
|
A planned improvement: `vat build` would bundle the plugin install logic into `dist/postinstall.js` — a fully self-contained script with no npm dependencies. The postinstall script would become simply `node ./dist/postinstall.js`. This eliminates `vibe-agent-toolkit` as a runtime dependency entirely, reducing install footprint for end users. Until then, Option C (runtime `vibe-agent-toolkit` dep) is the correct approach.
|
|
@@ -60,6 +60,10 @@ Four patterns cover most use cases. For full code examples, see `vibe-agent-tool
|
|
|
60
60
|
# Install VAT CLI globally
|
|
61
61
|
npm install -g vibe-agent-toolkit
|
|
62
62
|
|
|
63
|
+
# Or run without installing (works anywhere vat commands appear below)
|
|
64
|
+
npx vibe-agent-toolkit <command> # npm/Node.js
|
|
65
|
+
bunx vibe-agent-toolkit <command> # Bun
|
|
66
|
+
|
|
63
67
|
# Top-level orchestration
|
|
64
68
|
vat build # build all artifacts (skills then claude plugins)
|
|
65
69
|
vat verify # verify all artifacts (resources, skills, claude)
|
|
@@ -186,6 +190,18 @@ You've successfully adopted VAT when:
|
|
|
186
190
|
- [Runtime Adapters]()
|
|
187
191
|
- Examples: `@vibe-agent-toolkit/vat-example-cat-agents`
|
|
188
192
|
|
|
193
|
+
## Running VAT
|
|
194
|
+
|
|
195
|
+
VAT can be run without a global install:
|
|
196
|
+
|
|
197
|
+
```bash
|
|
198
|
+
vat <command> # If installed globally
|
|
199
|
+
npx vibe-agent-toolkit <command> # npm (downloads on demand)
|
|
200
|
+
bunx vibe-agent-toolkit <command> # Bun (downloads on demand)
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
All `vat` commands in this skill and sub-skills accept these alternatives.
|
|
204
|
+
|
|
189
205
|
## Getting Help
|
|
190
206
|
|
|
191
207
|
- **CLI Help:** `vat --help`, `vat skills --help`, etc.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@vibe-agent-toolkit/vat-development-agents",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.23-rc.6",
|
|
4
4
|
"description": "VAT development agents - dogfooding the vibe-agent-toolkit",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"keywords": [
|
|
@@ -64,13 +64,13 @@
|
|
|
64
64
|
"postinstall": "vat claude plugin install --npm-postinstall || exit 0"
|
|
65
65
|
},
|
|
66
66
|
"dependencies": {
|
|
67
|
-
"@vibe-agent-toolkit/agent-schema": "0.1.
|
|
68
|
-
"@vibe-agent-toolkit/cli": "0.1.
|
|
67
|
+
"@vibe-agent-toolkit/agent-schema": "0.1.23-rc.6",
|
|
68
|
+
"@vibe-agent-toolkit/cli": "0.1.23-rc.6",
|
|
69
69
|
"yaml": "^2.8.2"
|
|
70
70
|
},
|
|
71
71
|
"devDependencies": {
|
|
72
72
|
"@types/node": "^25.0.3",
|
|
73
|
-
"@vibe-agent-toolkit/resource-compiler": "0.1.
|
|
73
|
+
"@vibe-agent-toolkit/resource-compiler": "0.1.23-rc.6",
|
|
74
74
|
"ts-patch": "^3.2.1",
|
|
75
75
|
"typescript": "^5.7.3"
|
|
76
76
|
},
|