Skip to content

Instantly share code, notes, and snippets.

Show Gist options
  • Select an option

  • Save Dzhuneyt/fc198ebebade999842646e86ddfb7807 to your computer and use it in GitHub Desktop.

Select an option

Save Dzhuneyt/fc198ebebade999842646e86ddfb7807 to your computer and use it in GitHub Desktop.
Migrate Claude Code slash commands to skills

Migrate my local Claude Code slash commands to Skills.

Context: Claude Code recently unified slash commands and Skills into a single runtime namespace. Slash commands live at ~/.claude/commands/*.md; skills live at ~/.claude/skills/<name>/SKILL.md. Skills support richer frontmatter (allowed-tools, disable-model-invocation, argument-hint), live reload, and optional model auto-invocation. Commands still work but are legacy. Docs: https://code.claude.com/docs/en/skills

Do this end-to-end, pausing only at the decision points I call out:

Phase 1 — Audit (read-only)

  1. List every file in ~/.claude/commands/ (including nested dirs). For each .md, capture: full YAML frontmatter, body line count, whether it uses $ARGUMENTS, and whether it uses shell-injection syntax (!`...`).
  2. List every subdir in ~/.claude/skills/ with its SKILL.md frontmatter.
  3. List plugin dirs under ~/.claude/plugins/ and whether each owns commands/ or skills/.
  4. Detect and report:
    • Byte-identical duplicates within ~/.claude/commands/ (run md5 or equivalent). Multiple filenames pointing at identical content is a red flag for a bulk import.
    • Name collisions between user commands, user skills, and plugin skills/commands.
    • Likely third-party imports. Slash-command collections circulate on GitHub, gists, blog posts, and marketplace-style repos. Commands that came from one of those collections often share some of these traits:
      • Unusually large bodies (hundreds of lines) for what a slash command normally is
      • Abstract orchestrator / meta-prompt style rather than concrete task instructions
      • References to filesystem paths or tool conventions the user never configured (foreign home-dir layouts, unfamiliar CLI names)
      • Generic "Workflow Orchestrator", "multi-agent pipeline", or academic framework branding baked into the body
      • Boilerplate author signatures, ASCII banners, or emoji-heavy section headers
      • Cluster of files with matching prose style and formatting, distinct from the user's other commands For each suspicious file, pick a distinctive quoted phrase from its body and web-search it. Report the origin repo URL if found. Do not guess — if the search returns nothing, say so and let me decide.
    • Stray non-command files in ~/.claude/commands/ (settings files, nested .claude/ dirs, editor backups). These are misplaced and need relocation or removal.

Present a classification table before touching anything:

Command Provenance Size Proposed action
... custom / imported-from- / unknown N lines migrate / archive / delete

Phase 2 — Decide (ask me)

Ask me these three questions, exactly:

  1. Invocation: For migrated skills, should they be user-only (disable-model-invocation: true, same behavior as today), auto-triggerable by Claude, or mixed per command?
  2. Scope: 1:1 mapping, consolidation (e.g. merging related commands into one skill), or skip certain files?
  3. Originals: Delete, keep both, or archive to ~/.claude/commands.archive/?

For any files flagged as likely third-party imports, ask specifically whether to archive, delete, or migrate them. Default recommendation: archive, don't migrate — imported commands that the user doesn't actively use are usually dead weight.

For any auto-triggerable skills, propose a rewritten description starting with "Use when…" (the auto-trigger matcher reads the description to decide when to fire).

Phase 3 — Execute

  1. Create archive dirs if needed: ~/.claude/commands.archive/{imported,migrated-to-skills}/.
  2. Write a README.md in each archive dir noting the source (if known), the date, and a one-line reason.
  3. For each command to migrate:
    • Write ~/.claude/skills/<name>/SKILL.md with frontmatter:
      ---
      name: <name>
      description: <preserved or rewritten>
      allowed-tools: [<preserved>]   # if present
      disable-model-invocation: true  # omit for auto-triggerable
      ---
    • Preserve $ARGUMENTS placeholders verbatim — skills support them.
    • Copy the body unchanged.
    • Move the original file into the archive dir.
  4. Relocate stray files to their correct location. If the destination already exists, stop and ask.
  5. Fix malformed frontmatter (missing --- delimiters, bare YAML fields at top of file) when you encounter it.

Phase 4 — Verify

  1. Confirm ~/.claude/commands/ is empty or contains only things intentionally kept.
  2. Confirm ~/.claude/skills/ has the expected count.
  3. Confirm archive dirs are populated.
  4. Check Claude Code's live skill list: auto-triggerable skills should appear with "Use when…" descriptions; disable-model-invocation: true skills will NOT appear in the auto-trigger list (this is correct — they still work via /name).
  5. Report a final diff: what moved, what was migrated, what was archived, what was fixed.

Constraints

  • Do not delete anything. Move to archive instead.
  • Do not overwrite existing files (settings, skills, etc.) without confirming.
  • Touching ~/.claude/ may require disabling Claude Code's filesystem sandbox — expect "Operation not permitted" on first write and retry with sandbox disabled.
  • If you hit ambiguity at any point, stop and ask. Don't guess.

Start with Phase 1.

@Dzhuneyt
Copy link
Copy Markdown
Author

Drop this to a Claude Code session.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment