Skip to content

vt-t-skill-demote

Demote a global toolkit skill to product scope, regenerate its paths block, remove the global symlink (AD-2), and commit. Use when a global skill actually belongs to one product only.

Plugin: vt-toolkit
Category: Other
Command: /vt-t-skill-demote

Skill Demote

Restricts a global toolkit skill to a specific product scope.

When to Use

  • /vt-t-toolkit-review flagged a skill for product mismatch.
  • A skill marked scope: global should only appear in one product's repos.
  • Demoting removes the ~/.claude/skills/ symlink so the skill no longer auto-loads outside product repos (per AD-2).

Prerequisites

  • Skill exists in plugins/<plugin>/skills/<slug>/ (--plugin, default vt-base).
  • Target product is registered in intake/projects.yaml products:.
  • You are in the toolkit repo (or TOOLKIT_ROOT is set).

Execution

Run from the toolkit repo root:

# Default plugin is vt-base:
bash plugins/vt-toolkit/skills/skill-demote/scripts/demote.sh \
  vt-c-<skill-name> --to-product <ProductName>

# Any other plugin — the prefix must be that plugin's skill_prefix:
bash plugins/vt-toolkit/skills/skill-demote/scripts/demote.sh \
  --plugin vt-office vt-o-<skill-name> --to-product <ProductName>

demote.sh takes --plugin <name> (default vt-base) and reads that plugin's skill_prefix from its plugin.json, erroring if it declares none. The prefix itself is optional in the skill-name argument. This page previously hardcoded vt-base/vt-c-, so an agent following it never passed --plugin and could only demote base skills. The script: 1. Validates <ProductName> against intake/projects.yaml products: 2. Sets scope: product:[<ProductName>] in frontmatter 3. Runs regenerate-skill-paths.sh --write — writes the product paths block 4. Removes ~/.claude/skills/<prefix><slug> symlink (AD-2) 5. Removes <prefix><slug> -> <slug> from that plugin's manifest 6. Commits with message feat: demote <prefix><slug> to scope: product:[<ProductName>]

Edge Cases

  • Unknown product: script aborts — add the product to intake/projects.yaml products: first.
  • Symlink already absent: treated as a no-op for the remove step; commit still produced.
  • Re-promote: run /vt-t-skill-promote again if the skill should return to global scope.

Integration Points

  • plugins/vt-toolkit/skills/skill-promote/ — forward operation
  • plugins/vt-base/bin/regenerate-skill-paths.sh — builds paths block from projects.yaml
  • plugins/<plugin>/.claude-plugin/skill-symlinks.manifest — entry removed
  • Pre-commit hook: verifies resulting paths block is current after demote

Anti-patterns

  • Never hand-edit the AUTO-GENERATED paths block — the pre-commit hook blocks the commit. Use --write mode to regenerate.
  • Don't delete skills — demote preserves history; deletion is destructive and irreversible.

Success Criteria

  • scope: product:[<ProductName>] in SKILL.md frontmatter.
  • AUTO-GENERATED block present with correct product glob patterns.
  • No ~/.claude/skills/<prefix><slug> symlink (AD-2).
  • Manifest entry removed.
  • git log -1 shows the demote commit.