Claude Code Skills and Plugins: The Developer’s Complete Guide

Imagine spending less time on boilerplate and more on creative coding. With Claude Code skills and plugins, you can teach Claude to handle repetitive tasks, integrate your favorite tools, and turn your terminal into a superpower. This guide walks you through everything you need to know to build your own extensions; from a simple skill to a full MCP server; so you can work faster and smarter.

First, if you’re new to Claude Code itself, consider this: Claude Code is not just a chat interface. It’s an extensible AI workspace that learns your patterns, executes tools, and adapts to your workflow. The secret to unlocking its full potential lies in skills, plugins, hooks, and MCP servers; four extension mechanisms that let you customize Claude Code to fit your exact needs. In this guide, we’ll break them down, show you how to build each, and share best practices from production use.

The Claude Code Extension Ecosystem

Claude Code offers four distinct ways to extend its capabilities. They serve different purposes and can be combined for powerful results:

Think of skills as the entry point for most developers. They let you package prompts, examples, and structured guidance into a reusable format. Plugins take things further by adding new commands and system-level hooks. And when you need to connect Claude to the outside world, MCP servers bridge the gap. We’ll explore each in depth.

Anatomy of a Skill

A Claude Code skill is defined by a single SKILL.md file. This file uses frontmatter to describe when the skill should be suggested, followed by the instructional content that Claude will present to the user (or use internally). Here’s the structure:

Frontmatter

The frontmatter is a YAML block at the top of the file that tells Claude Code when to activate the skill. Important fields include:

• name: A unique identifier for your skill.
• description: A short summary of what the skill does.
• triggers: Patterns that match user requests. If the user’s message matches any trigger, Claude Code will suggest this skill.
• context: Additional data (e.g., file patterns) to refine activation.

For example, a skill that helps with JSON formatting might trigger on messages containing “format json” and only when the active file has a .json extension.

Instruction Body

The body of the SKILL.md is markdown-formatted text. This is where you provide step-by-step instructions, code snippets, and examples. Claude will render this content when the skill is invoked. The best practices for the instruction body are:

• Progressive disclosure: Put the most critical information first. Add details in expandable sections using HTML <details> tags or by linking to reference materials.
• Use imperative language: “Run this command” rather than “You might want to run this command”.
• Include concrete examples: Show exact input and expected output.
• Explain the ‘why’: Briefly note why a step matters.

Here’s a skeleton of a skill file:

---
name: json-formatter
description: Format and validate JSON files
triggers:
  - format json
  - validate json
context:
  file_extensions: [.json]
---

# JSON Formatter

Use this skill to reformat messy JSON and catch syntax errors.

## Steps

1. Copy your JSON into the clipboard.
2. Run Format Document from the command palette.
3. Review the formatted output.


Advanced: Minify
If you need minified JSON, use json.minify() in the console.

Save this file in ~/.claude/skills/ and Claude Code will automatically load it.

Building Your First Skill: A Step-by-Step Tutorial

Let’s create a practical skill that formats JSON and explains common errors. This example will illustrate the entire workflow.

Step 1: Create the Skill Directory

Decide whether the skill should be available to just you (user-scoped) or to everyone on a project (project-scoped).

• User-scoped: store in ~/.claude/skills/.
• Project-scoped: store in PROJECT_ROOT/.claude/skills/.

We’ll create a directory called json-formatter inside the project’s skills folder.

mkdir -p .claude/skills/json-formatter
cd .claude/skills/json-formatter

Step 2: Write the Frontmatter

Create a file named SKILL.md with the following content:

---
name: json-formatter
description: Formats and validates JSON, with explanations of errors.
triggers:
  - format json
  - validate json
  - fix json
context:
  file_extensions: [.json]
---

The triggers array tells Claude Code to suggest this skill when the user mentions any of these phrases. The context.file_extensions restricts the skill to JSON files, avoiding noise in other file types.

Step 3: Write the Instruction Body

Now add the instructional content. We’ll include a quick method, an advanced option, and a troubleshooting section using progressive disclosure.

# JSON Formatter

Quickly clean up messy JSON and catch syntax errors.

## Quick Use

1. Select the JSON text (or place cursor in a JSON file).
2. Run the command Format Document (or Format Selection).
3. The formatted JSON appears, properly indented.

If the JSON is invalid, Claude will point out the error location.

## Advanced: Minify JSON

Sometimes you need a single-line version for URLs or config files.

1. Open the command palette.
2. Run Claude Code: Run Skill → json-formatter → Minify JSON.
3. The minified output is copied to your clipboard.


Troubleshooting

- Error: Unexpected token Check for missing commas or stray characters. Skill not appearing Ensure the file is saved with the correct format. .json extension and that you're in a workspace with the skill installed.
- Large files cause slowdown Split the file or format it in chunks.

Notice the use of bold for emphasis and a <details> block to hide advanced troubleshooting until needed. This keeps the interface clean.

Step 4: Test Your Skill

Open a JSON file in Claude Code, type “format json” in the chat, and see if the skill suggestion appears. Click it, and Claude should display the formatted JSON. Experiment with the triggers to confirm they match your intent.

If the skill doesn’t trigger, check the logs (View → Toggle Developer Tools) for any loading errors. Make sure the YAML syntax is valid and the file is placed in the correct directory.

Plugins and System-Level Extensions

While skills are great for curated instructions, plugins let you add new commands, tools, and hooks directly into Claude Code’s interface. Plugins are written in JavaScript or TypeScript and run in the same process as Claude Code, giving them deep integration capabilities.

Plugin Structure

A plugin is a folder containing a plugin.json manifest and one or more script files. The manifest defines:

• name, version, description
• commands: Array of new slash commands the plugin provides.
• hooks: Event listeners that run code on specific Claude Code events (e.g., on file save, before a submission).
• permissions: What the plugin is allowed to do (read files, access network, etc.).

Here’s a minimal plugin.json for a plugin that adds a /format-json command:

{
  "name": "json-formatter-plugin",
  "version": "0.1.0",
  "description": "Adds a slash command to format JSON",
  "commands": [
    {
      "name": "format-json",
      "description": "Format the current buffer as JSON",
      "handler": "formatJson"
    }
  ],
  "hooks": {},
  "permissions": ["read", "write"]
}

The corresponding plugin.js implements the formatJson function. Plugins have access to Claude Code’s internal APIs, so you can call built-in tools, modify the editor, or even spawn subagents.

Installing and Enabling Plugins

Place the plugin folder in ~/.claude/plugins/ or in the project’s .claude/plugins/ directory. Then run /plugin enable json-formatter-plugin in Claude Code. The plugin will be loaded and its commands become available in the command palette.

Plugins are powerful but require careful handling of permissions. Claude Code will prompt the user to approve potentially dangerous operations. Always follow the principle of least privilege.

MCP Servers – Connecting External Tools

The Model Context Protocol (MCP) is an open standard that allows Claude Code to communicate with external servers that provide tools. An MCP server runs as a separate process and speaks JSON-RPC over stdio or HTTP. Claude Code connects to it, discovers available tools, and invokes them as needed.

MCP servers are the most flexible extension point because they can be written in any language and can access any resource the server can reach. They are ideal for integrating with databases, custom APIs, or legacy systems.

How MCP Works

1. Claude Code launches the MCP server (or connects to an existing one) using the configuration in claude_desktop_config.json or ~/.claude/config.yaml.
2. The server sends a list of available tools, each with a name, description, and JSON schema for input parameters.
3. When Claude decides a tool is appropriate, it sends an invocation request to the server.
4. The server executes the tool and returns the result.

Because MCP is language-agnostic, you can write a server in Python, Node.js, Go, Rust, etc. The only requirement is to implement the JSON-RPC message format.

Quick Example: A Weather MCP Server

Suppose you want Claude to be able to fetch the current weather. You could write a simple MCP server in Python that exposes a get_weather tool. The server would use an HTTP client to call a weather API, format the result, and return it to Claude Code. Once the server is registered, Claude can use the tool in conversations just like any built-in capability.

For a complete, production-ready example, check out our step-by-step guide on Build Custom MCP Servers for Hermes Agent: Complete Guide. That tutorial covers authentication, error handling, and deployment patterns that apply to any MCP server project.

Advanced Patterns for Power Users

Once you’re comfortable with basic skills and plugins, you can combine them to create sophisticated workflows. Here are some high-value patterns used by experienced Claude Code users.

Subagent Spawning

Claude Code can create subagents; independent instances of Claude that run in the background with their own context. You can spawn a subagent from a skill using the provided tools. /spawn command or via the plugin API. This is useful for parallel tasks like running tests while you continue coding, or delegating a long-running analysis.

Multi-Agent Orchestration

For complex projects, you might define multiple specialized agents (e.g., one for frontend, one for backend, one for testing) and have them collaborate. Claude Code’s agent view and /goal command help coordinate these agents toward a shared objective. This pattern is described in detail in our earlier guide on Hermes Agent: Persistent AI for Cross-Platform Automation.

Worktree Strategies

When making large changes, consider using Git worktrees to isolate experimental branches. Claude Code can manage worktrees for you, allowing you to spin up a temporary branch, test a skill, and then merge back if successful. This reduces the risk of disrupting your main workspace.

Best Practices for Production Skills

Before sharing your skill with the team or the world, follow these guidelines to ensure reliability and maintainability.

• Test with multiple Claude models: Verify that your skill works with both Claude Sonnet and Claude Opus, as context handling can differ.
• Handle errors gracefully: Anticipate missing files, invalid JSON, or network timeouts. Provide clear error messages that guide the user to a fix.
• Keep prompts focused: A skill’s instruction should be concise and to the point. Long, meandering instructions dilute Claude’s attention.
• Version your skills: Include a version number in the frontmatter and keep a changelog. This helps with debugging and updates.
• Respect user privacy: Do not send sensitive data to external services without explicit consent. If your skill uses an API, require an API key from the user rather than hardcoding your own.

These practices will make your skills robust and trustworthy.

Real-World Examples from the Community

The Claude Code ecosystem already boasts hundreds of community-contributed skills. Here are a few standouts that demonstrate what’s possible:

• JSON to CSV Converter: A skill that reads JSON from the clipboard and produces a CSV table, ideal for data analysts.
• Regex Playground: An interactive skill that explains regular expressions in plain English and lets you test them against sample text.
• API Cost Calculator: Estimates the cost of an API call to various LLM providers based on token counts.
• Commit Message Generator: Uses the current git diff to generate a conventional commit message.
• Code Review Assistant: A skill that runs static analysis and suggests improvements, integrating with linters and security scanners.

These examples show how skills can range from simple utilities to full-featured assistants. Start small, iterate based on feedback, and gradually add sophistication.

Debugging and Troubleshooting

Even with careful development, issues can arise. Here are common pitfalls and how to resolve them.

• Skill not triggering: Check the trigger phrases and context restrictions. Use the /skills command to see if the skill is loaded and active. Ensure the YAML syntax is valid (use a YAML linter).
• Claude ignoring the skill instructions: The instruction body might be too long or ambiguous. Simplify and move extraneous details into <details> blocks. Also check that you’re using the correct heading hierarchy.
• Plugin commands not appearing: Verify plugin.json syntax and that the plugin folder is in the right directory. Restart Claude Code after installing. Look for errors in the developer console.
• MCP server connection refused: Ensure the server is running and that the configuration points to the correct URL or executable. Check firewall rules if using TCP. Enable logging on the server to see incoming connections.
• Unexpected tool arguments: The JSON schema for MCP tool parameters must match what Claude sends. Use strict types and provide default values to avoid missing parameters.

When in doubt, consult the logs. Claude Code’s developer tools show the raw communication with skills and plugins, which can reveal mismatches.

Conclusion

Claude Code’s extensibility is a game-changer for developer productivity. By crafting skills, plugins, and MCP servers, you can mold Claude into an ideal partner for your specific workflow. Whether you’re automating JSON formatting, connecting to internal APIs, or orchestrating multiple agents, the extension ecosystem provides the building blocks.

Start small: build a simple skill that solves a personal pain point. Test it, refine it, and share it with your team. As you grow more confident, move on to plugins and MCP servers. And if you want to dive deep into MCP, be sure to read our dedicated guide on Build Custom MCP Servers for Hermes Agent: Complete GuideIt covers advanced patterns, authentication, and deployment at scale.

The next time you find yourself repeating a task in Claude Code, ask: could this be a skill? The answer is probably yes. Happy building!

Ready to extend Claude Code? Learn how to How to Build a Claude Code Plugin, Securing MCP Servers for Claude Code, and Claude Code Patterns: Subagents, Worktrees, Orchestration.

Frequently Asked Questions