Skip to content

vt-t-skill-promote

Promote a repo-local skill to the global toolkit with scope global, add its manifest entry and symlink, and commit. Use when a skill developed in a project repo should become available toolkit-wide.

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

Skill Promote

Moves a skill from a project repo's .claude/skills/ directory into the global toolkit.

Target plugin. promote.sh takes --plugin <name> and defaults to vt-base. It reads that plugin's skill_prefix from its plugin.json and hard-errors if the skill's name: does not carry it. So promoting into vt-office needs --plugin vt-office and a vt-o-* name — this page used to hardcode vt-base/vt-c- throughout, so an agent following it promoted every new skill into the base plugin no matter where it belonged.

When to Use

  • A skill was written inside one project repo and should now be available across all repos.
  • The skill name already follows the target plugin's prefix convention (vt-c-* for the default vt-base; vt-d-, vt-o-, vt-t-, vt-p-, vt-b-, vt-v-, vt-f- for the others).
  • The target slug does not yet exist in that plugin's skills/.

Prerequisites

  • Skill has name: <target plugin's prefix>* in its frontmatter.
  • You are in the toolkit repo (or TOOLKIT_ROOT env var is set).
  • The target plugins/<plugin>/skills/<slug>/ does not exist.

Execution

Run from the toolkit repo root:

# Default target is vt-base:
bash plugins/vt-toolkit/skills/skill-promote/scripts/promote.sh \
  <source-SKILL.md>

# Any other plugin — the prefix must match that plugin's skill_prefix:
bash plugins/vt-toolkit/skills/skill-promote/scripts/promote.sh \
  --plugin vt-office <source-SKILL.md>

The script: 1. Copies the skill directory to plugins/<plugin>/skills/<slug>/ 2. Sets scope: global in the frontmatter (overrides any existing scope) 3. Runs regenerate-skill-paths.sh --write — no paths block for global skills 4. Appends <prefix><slug> -> <slug> to that plugin's manifest 5. Creates ~/.claude/skills/<prefix><slug> symlink 6. Commits with message feat: promote <prefix><slug> to global toolkit scope

Edge Cases

  • Target already exists: script aborts — run /vt-t-skill-demote to change scope of an existing skill, not promote.
  • Name missing the target plugin's prefix: script aborts — rename the skill, or pass the --plugin whose prefix it already carries.
  • Missing name: frontmatter: script aborts — add the field first.

Integration Points

  • plugins/vt-toolkit/skills/skill-demote/ — reverse operation
  • plugins/vt-base/bin/regenerate-skill-paths.sh — regenerates paths block
  • plugins/<plugin>/.claude-plugin/skill-symlinks.manifest — updated with new entry

Success Criteria

  • plugins/<plugin>/skills/<slug>/SKILL.md has scope: global.
  • No AUTO-GENERATED block in the file (global scope → no paths block).
  • ~/.claude/skills/<prefix><slug> symlink exists.
  • Manifest contains <prefix><slug> -> <slug>.
  • git log -1 shows the promote commit.