How to Create a Custom Skill for Claude Code: A Complete Developer Guide

Claude Code learns new capabilities through declarative SKILL.md files that define cardinal rules, invocation triggers, and decision trees to guide the agent's behavior.

When you need to extend Claude Code with domain-specific workflows, you create a custom skill inside your plugin's .claude directory. According to the anthropics/claude-plugins-community repository, these skills are self-contained markdown documents that declare policy rather than imperatively coding logic, enabling deterministic, audit-friendly behavior that persists across model upgrades.

Understanding the Skill Architecture

A skill is a read-only policy document that lives in a plugin's folder structure. When Claude Code receives a user request, it scans every installed skill for a matching trigger in the "When to invoke" section. Upon a match, the agent loads the skill's cardinal rules—immutable guardrails that override any other reasoning—and follows the decision tree to locate the appropriate supplemental files.

The architecture separates concerns into distinct directories:

• SKILL.md – The core definition containing front-matter, description, cardinal rules, and decision tree mappings.
• references/ – Model-agnostic concept documents explaining reusable patterns like "voice continuity" or "no-music-no-subtitles".
• pipelines/ – Multi-step Bash or MCP workflows for complex operations like multi-segment video generation.
• models/ – Provider-specific cards listing flags, gotchas, and prompt skeletons for individual AI models.

See the canonical implementation in quickdesign/skills/quickdesign/SKILL.md for a concrete example of this structure.

Step-by-Step Guide to Building a Custom Skill

1. Initialize the Skill Directory

Create a folder for your skill under the local plugins directory:

mkdir -p ~/.claude/plugins/my-skill
cd ~/.claude/plugins/my-skill

2. Create the SKILL.md Definition

Create a SKILL.md file at the root of your skill folder. This file must contain a YAML front-matter block followed by four required sections:

---
name: my-skill
description: Perform X-Y workflow using an internal CLI tool.
---

# My Skill – Core Definition

## When to invoke

- **X-Y request** — "run the X-Y process", "generate a Y-report", "do X-Y on the dataset".

## Cardinal rules

1. **Never run the CLI without an explicit `--confirm` flag**. Abort if the flag is missing.
2. **All user-provided files must be passed as `--input` references**; never embed raw file contents in the prompt.
3. **If the user asks for a preview, generate a low-cost preview first** and ask for approval before the full run.

## Decision tree — which doc to open first

| Request | Start here |
|---|---|
| Full X-Y run | `pipelines/full-run.md` |
| Preview only | `pipelines/preview.md` |
| Model-specific options | `models/default-model.md` |

The front-matter defines the skill's identity, while the cardinal rules act as a hard safety net that the runtime enforces even if the model's reasoning chain suggests otherwise.

3. Add Supporting Documentation

Create the referenced files to support your decision tree:

• References: Place reusable concepts in references/voice-continuity.md (following the pattern in quickdesign/skills/quickdesign/references/voice-continuity.md).
• Pipelines: Store multi-step workflows in pipelines/ugc-video.md (see quickdesign/skills/quickdesign/pipelines/ugc-video.md for Bash/MCP sequence examples).
• Models: Create provider-specific cards like models/seedance-2.0-r2v.md (reference quickdesign/skills/quickdesign/models/seedance-2.0-r2v.md for the format).

4. Register the Skill in plugin.json

Create .claude-plugin/plugin.json to register your skill with Claude Code:

{
  "name": "my-skill",
  "description": "Custom skill for X-Y workflow",
  "skills": [
    {
      "name": "my-skill",
      "path": "SKILL.md"
    }
  ]
}

Refer to quickdesign/.claude-plugin/plugin.json for the exact schema and additional metadata options.

5. Add Marketplace Metadata (Optional)

To enable one-click installation via the plugin marketplace, create .claude-plugin/marketplace.json:

{
  "name": "my-skill",
  "description": "My custom skill",
  "url": "https://github.com/your-repo/your-skill",
  "type": "skill"
}

See quickdesign/.claude-plugin/marketplace.json for the complete marketplace entry format.

6. Test the Skill

Launch Claude Code and issue a request matching your "When to invoke" triggers. Verify that:

• Claude loads the skill and prints the cardinal rules in the chat.
• The agent follows the decision tree to the correct pipeline or model file.
• Violations of cardinal rules (such as missing --confirm flags) cause the operation to abort.

Adjust the rules or decision tree until the behavior matches your expectations.

How Cardinal Rules Enforce Safety

Because Claude Code treats every skill as a read-only policy document, the cardinal rules function as runtime-enforced constraints. Even if the model's internal reasoning attempts to select a different model or omit a required reference, the runtime automatically enforces the rule and aborts the operation. This guarantees that custom skills remain deterministic, audit-friendly, and compatible with future model upgrades.

Summary

• Skills are declarative: All logic lives in markdown files (SKILL.md) rather than imperative code.
• Structure matters: Organize supporting files into references/, pipelines/, and models/ subdirectories.
• Safety first: Cardinal rules in SKILL.md act as immutable guardrails that the runtime enforces regardless of model reasoning.
• Registration required: Every skill must be listed in .claude-plugin/plugin.json to be discovered.
• Local path: Install custom skills in ~/.claude/plugins/<your-skill>/ for immediate availability.

Frequently Asked Questions

What is the difference between a skill and a plugin?

A plugin is the container that registers capabilities with Claude Code through plugin.json, while a skill is a specific type of capability defined within that plugin. A single plugin can contain multiple skills, each with its own SKILL.md, triggers, and rules. The plugin handles installation and discovery, while the skill defines the behavioral policy.

Where should I store custom skills locally?

Place custom skills in ~/.claude/plugins/<your-skill>/ or within any plugin's .claude directory structure. Claude Code scans these locations at startup to load available skills. Ensure each skill folder contains a SKILL.md file and any referenced subdirectories (references/, pipelines/, models/).

How do cardinal rules enforce safety?

Cardinal rules are numbered statements in SKILL.md that the Claude Code runtime treats as hard constraints. If the model's reasoning chain generates an action that violates a rule (such as running a CLI without a required flag), the runtime intercepts and aborts the operation. This makes skills deterministic and prevents deviation from business logic even as underlying models evolve.

Can skills invoke external tools or APIs?

Yes. Skills can reference pipelines containing Bash commands or MCP (Model Context Protocol) tool invocations. These pipelines live in the pipelines/ directory and are referenced from the decision tree in SKILL.md. The skill declares which pipeline to run, but the actual imperative execution (API calls, script runs) happens in those separate files, maintaining the clean separation between policy (SKILL.md) and implementation (pipelines).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}