Skip to content

Verify Setup

After installation, verify that all components are correctly deployed.

Automated Verification

Run the integrity check:

cd V025-claude-toolkit
scripts/setup.sh --verify

This checks:

Component What's verified
Plugin symlink ~/.claude/plugins/company-claude-toolkit exists and resolves
CLAUDE.md Exists and matches golden copy
settings.json Exists and matches golden copy
Plugin enablement The toolkit plugin is actually enabled and resolvable — not merely deployed to disk. Three legs, all required (SPEC-171 SC-2): enabledPlugins["vt-base@visitrans"] is literally true; claude plugin list reports it enabled; claude plugin details exits 0
Marketplace registry known_marketplaces.json registers the toolkit marketplace, and the plugin cannot resolve without it — MEASURED: with the settings.json declaration alone the CLI reports "failed to load" and plugin details exits 1. The toolkit writes it on every --safe/--full; --verify asserts our entry is present, not merely that the file exists (BUG-050)
Plugin registry installed_plugins.json likewise — --verify asserts it lists vt-base@visitrans. Both legs are filesystem-level, so they still report the truth on a machine with no claude CLI on PATH
Skill symlinks All manifest entries resolve to valid directories
Hook symlinks All manifest entries resolve to valid files
Command symlinks All manifest entries resolve to valid files
Agent files All agent .md files present
Output styles All output style files present

Reading the Output

  [OK]  Plugin symlink exists and resolves
  [OK]  Plugin enabled and resolvable: vt-base@visitrans
  [OK]  CLAUDE.md matches golden copy
  [OK]  settings.json matches golden copy
  [OK]  100/100 skill symlinks valid
  [OK]  8/8 hook symlinks valid
  [OK]  36/36 command symlinks valid

Exact counts depend on installed plugins and toolkit version.

When the plugin is not enabled

  [ERR] Plugin NOT enabled: vt-base@visitrans is absent from enabledPlugins in ~/.claude/settings.json

This is the check that matters most, because it is the one that was missing. Every enforcement hook — the secret scanner, the partition guard, the supply-chain guard — lives in the plugin and fires only while the plugin is enabled. A deployed-but-disabled toolkit looks completely healthy by every other line above, and ran that way for six months (BUG-036).

The verdict reflects the flag, never a file's existence, and never claude plugin details' exit code on its own: that command keys on the presence of the enabledPlugins key rather than its value, so a plugin you explicitly set to false still exits 0.

If claude is not on your PATH, legs 2 and 3 report [--] instead of [ERR]:

  [--]  Plugin enable flag is set for vt-base@visitrans; resolution not checked (no claude CLI on PATH)

That is not a failure — a missing CLI says something about the machine, not about the install.

  • [OK] — Component is healthy
  • [!!] — Warning, non-critical difference (e.g., config differs from golden copy)
  • [ERR] — Error, component is missing or broken

Manual Verification

Check Skills Load in Claude Code

Start Claude Code in any project and run:

/vt-d-0-start

If the skill runs, your skills are loading correctly.

# Plugin symlink
ls -la ~/.claude/plugins/company-claude-toolkit

# Skill symlinks (sample)
ls -la ~/.claude/skills/ | head -20

# Hook symlinks
ls -la ~/.claude/hooks/

# Plugin junction
Get-Item "$env:USERPROFILE\.claude\plugins\company-claude-toolkit" | Select-Object Name, Target

# Skill junctions
Get-ChildItem "$env:USERPROFILE\.claude\skills" | Select-Object Name, Target

# Hook links
Get-ChildItem "$env:USERPROFILE\.claude\hooks" | Select-Object Name, Target

Common Issues

Symptom: [ERR] skill symlinks broken in verify output.

Cause: The toolkit repository was moved or the symlink targets no longer exist.

Fix: Re-run the setup:

scripts/setup.sh --safe

Skills Not Loading in Claude Code

Symptom: /vt-d-0-start or other skills aren't recognized.

Possible causes:

  1. Symlinks not created — Run scripts/setup.sh --verify to check
  2. Unrecognized frontmatter — A SKILL.md has an invalid field (e.g., argument-hint is not recognized and silently prevents loading)
  3. Claude Code not restarted — Skills are loaded at session start; restart Claude Code after installation

Config Drift

Symptom: [!!] CLAUDE.md differs from golden copy in verify output.

Cause: Local changes were made to ~/.claude/CLAUDE.md or settings.

Options:

  • Review the diff: scripts/setup.sh --diff
  • Restore from golden copy: scripts/setup.sh --safe
  • Keep local changes and back them up: scripts/setup.sh --backup (writes ~/.claude.backup-<timestamp>; the repository is not modified)

Symptom: mklink commands fail with "You do not have sufficient privilege."

Fix:

  • For directory junctions (mklink /J): These should work without admin rights. Ensure you're using /J, not /D.
  • For file symlinks (mklink): Enable Developer Mode in Windows Settings > System > For developers, or run the terminal as Administrator.