Migrate Slash Commands To Skills: A Plugin Guide

Hey guys! So, you're looking to move your slash custom commands from a plugin to skills? Awesome! This guide will walk you through the process, using the Claude Code plugin system as a reference. We'll cover everything from understanding the plugin structure to implementing skills, so buckle up!

Understanding the Claude Code Plugin System

Before diving into the migration, let's get familiar with the Claude Code plugin system. This system allows you to extend Claude's functionality through various components like commands, agents, skills, hooks, and more. Plugins are essentially bundles of code that add new features or integrations to Claude. The plugin system is designed to be flexible and powerful, allowing you to create custom solutions tailored to your specific needs. This flexibility is key, as it enables you to adapt Claude to a wide range of workflows and use cases.

Plugin Components

Plugins can offer five types of components:

1. Commands: These are custom slash commands that integrate directly into Claude Code's command system. Think of them as shortcuts for specific actions or tasks.
2. Agents: Specialized sub-agents that Claude can automatically call upon when needed. These are like expert assistants for particular tasks.
3. Skills: These extend Claude's capabilities and are called by Claude based on the task context. Skills are model-callable, meaning Claude decides when to use them.
4. Hooks: Event handlers that automatically respond to Claude Code events. These allow you to trigger actions based on what's happening in Claude.
5. MCP Servers: Model Context Protocol servers that connect Claude Code to external tools and services.

Diving into Skills

Skills are what we're focusing on today. They're a way to enhance Claude's abilities by providing specific functionalities. Claude decides when to use these skills based on the task at hand. This means you don't have to manually invoke them; Claude figures it out automatically. Skills are model-callable and live in the skills/ directory of your plugin. Each skill resides in its own subdirectory, containing a SKILL.md file that defines the skill's purpose and functionality. You can also include optional reference.md files for additional documentation and scripts/ directories for supporting code. For example, if you have a PDF processing skill, it might look like this:

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (optional)
│   └── scripts/ (optional)

When Claude identifies a task that matches the skill's description, it automatically invokes the skill to handle the task. This seamless integration makes skills a powerful way to extend Claude's capabilities without requiring manual intervention.

Migrating Slash Commands to Skills: The Process

Okay, let's get down to business. How do you actually migrate your slash custom commands to skills? Here's a step-by-step guide:

1. Analyze Your Slash Commands

Start by examining your existing slash commands. What do they do? What inputs do they take? What outputs do they produce? Understand the core functionality of each command. This analysis will help you determine how to best translate them into skills. For example, if you have a command that formats code, you'll want to understand the different formatting options it supports and how it interacts with the code.

2. Design Your Skills

Based on your analysis, design your skills. Think about how Claude should use these skills. What types of tasks should trigger them? What information does Claude need to provide to the skill? Consider breaking down complex commands into smaller, more focused skills. For instance, instead of having one large "code manipulation" skill, you might have separate skills for "code formatting," "code analysis," and "code refactoring." This modular approach makes your skills more reusable and easier to maintain.

3. Create the SKILL.md Files

For each skill, create a SKILL.md file in its own subdirectory within the skills/ directory. This file should clearly describe the skill's purpose, capabilities, and how Claude should use it. Use the following structure:

---
description: A brief explanation of what this agent specializes in.
capabilities: ["task1", "task2", "task3"]
---

# Agent Name

A detailed explanation of the agent's role, expertise, and when Claude should invoke it.

## Features

- Specific tasks the agent excels at
- Another specialized feature
- When to use this agent vs. others

## Context and Examples

Provide examples of when this agent should be used and the kinds of problems it solves.

4. Implement the Skill Logic

If your skill requires custom code, implement it in the scripts/ directory. You can use any language you like, such as Python, JavaScript, or Bash. Make sure your code is well-documented and easy to understand. Consider using external libraries or APIs to enhance your skill's functionality. For example, if you're creating a skill that interacts with a database, you might use a database client library to simplify the interaction.

5. Test Your Skills

Thoroughly test your skills to ensure they work as expected. Use different inputs and scenarios to verify their functionality. Pay attention to error handling and edge cases. Consider creating unit tests to automate the testing process. This will help you catch bugs early and ensure that your skills remain reliable over time.

6. Deploy Your Plugin

Once you're satisfied with your skills, deploy your plugin to Claude. Follow the instructions in the Claude Code documentation to package and deploy your plugin. Make sure to include all necessary files and dependencies. Consider using a version control system to manage your plugin's code and track changes. This will make it easier to collaborate with others and revert to previous versions if necessary.

Example: Migrating a Code Formatting Command

Let's say you have a slash command that formats code according to a specific style guide. Here's how you might migrate it to a skill:

1. Analyze: The command takes code as input and outputs formatted code.
2. Design: Create a skill called "code-formatter" that formats code using a predefined style guide. Claude should use this skill whenever it needs to format code.
3. SKILL.md: Create a SKILL.md file in the skills/code-formatter/ directory:

---
description: Formats code according to a predefined style guide.
capabilities: ["format code"]
---

# Code Formatter

This skill formats code using a predefined style guide. Claude should use this skill whenever it needs to format code to ensure consistency and readability.

## Features

- Formats code in various languages (Python, JavaScript, etc.)
- Enforces coding style rules
- Improves code readability

## Context and Examples

Use this skill whenever you need to format code. For example, if you have code that doesn't conform to the style guide, use this skill to format it.

4. Implementation: Implement the code formatting logic in a script (e.g., scripts/format.py).
5. Test: Test the skill with different code snippets to ensure it formats them correctly.
6. Deploy: Deploy the plugin to Claude.

Plugin Structure Deep Dive

To ensure everything is in the right place, let's look at the standard plugin layout:

enterprise-plugin/
├── .claude-plugin/           # Metadata directory
│   └── plugin.json          # Required: Plugin manifest
├── commands/                 # Default command location
│   ├── status.md
│   └── logs.md
├── agents/                   # Default agent location
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── skills/                   # Agent skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── hooks/                    # Hook settings
│   ├── hooks.json           # Main hook settings
│   └── security-hooks.json  # Additional hooks
├── .mcp.json                # MCP server definition
├── .lsp.json                # LSP server settings
├── scripts/                 # Hook and utility scripts
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # License file
└── CHANGELOG.md             # Version history

File Location Reference

Debugging and Development Tools

Debugging is crucial. Use claude --debug to check plugin loading details. This shows which plugins are loaded, manifest errors, command registrations, and MCP server initializations. Remember the common issues like invalid plugin.json, incorrect directory structure, and scripts not being executable.

Troubleshooting Hooks

If your hook scripts aren't running, ensure the script is executable (chmod +x script.sh), check the shebang line (#!/bin/bash), and confirm the path uses ${CLAUDE_PLUGIN_ROOT}.

MCP Server Troubleshooting

For MCP servers, verify the command exists and is executable, all paths use ${CLAUDE_PLUGIN_ROOT}, and check the server logs with claude --debug.

Avoiding Directory Structure Mistakes

Ensure components are in the plugin root, not inside .claude-plugin/. Only plugin.json belongs in .claude-plugin/. If components are inside, move them to the plugin root.

Conclusion

Migrating slash commands to skills can greatly enhance Claude's capabilities. By following these steps and understanding the Claude Code plugin system, you can create powerful and flexible skills that seamlessly integrate with Claude. Happy coding, and feel free to ask if you have any questions!