publish-skill

Publish Skill

Manage skills between a private skills directory and a public toolkit repo.

Configuration

This skill stores its configuration in a JSON file next to this SKILL.md:

<skill-base-dir>/config.json

The config file contains:

{
  "SKILLS_DIR": "~/.claude/skills",
  "TOOLKIT_DIR": "~/path/to/your/toolkit",
  "TOOLKIT_SKILLS": "~/path/to/your/toolkit/skills"
}

First-run setup

Before executing ANY workflow, check if config.json exists in this skill's directory. If it does NOT exist:

1. Tell the user: "This is your first time running publish-skill. I need to know where your toolkit repo and skills directory are."
2. Ask for SKILLS_DIR — "Where are your Claude Code skills stored?" (default: ~/.claude/skills)
3. Ask for TOOLKIT_DIR — "Where is your public toolkit git repo?" (no default — user must provide this)
4. Set TOOLKIT_SKILLS to $TOOLKIT_DIR/skills and confirm with user
5. Write the config to config.json next to this SKILL.md
6. Continue with the requested workflow

If config.json exists, read it and use those values for all paths below.

All commands below use $SKILLS_DIR, $TOOLKIT_DIR, and $TOOLKIT_SKILLS — substitute the values from config.json.

Arguments

$ARGUMENTS

Input	Action
promote <skill-name>	Move private skill to public toolkit, replace local with symlink
fork <skill-name> [--public-name <name>]	Create generalized public copy, keep private version
adopt <skill-name-or-url>	Install public skill and customize as private
status	Show which skills are private, public, or symlinked
diff <skill-name>	For forked skills: show diff between private and public versions
Empty or help	Explain available modes

Workflow: Status

Run this first to understand the current state.

# List all skills and their status
for dir in $SKILLS_DIR/*/; do
  name=$(basename "$dir")
  if [ -L "${dir%/}" ]; then
    target=$(readlink -f "${dir%/}")
    echo "SYMLINKED  $name -> $target"
  elif [ -d $TOOLKIT_SKILLS/"$name" ]; then
    echo "FORKED     $name (private + public versions)"
  else
    echo "PRIVATE    $name"
  fi
done

# Show public skills not installed locally
for dir in $TOOLKIT_SKILLS/*/; do
  name=$(basename "$dir")
  [ -e $SKILLS_DIR/"$name" ] || echo "PUBLIC_ONLY $name (not installed locally)"
done