# How to Define a Skill-Based Claude Plugin: Complete Guide to the Community Repository

> Learn how to define a skill-based Claude plugin. Discover modular, declarative workflows in Markdown using YAML and the Model Context Protocol (MCP).

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-09-04

---

**TLDR: A skill-based Claude plugin is a modular, declarative workflow defined in Markdown with YAML front-matter that Claude executes sequentially as a reusable capability through the Model Context Protocol (MCP) runtime.**

A skill-based Claude plugin packages complex user flows into deterministic, auditable steps that Claude invokes during conversations. Within the `anthropics/claude-plugins-community` repository, these plugins follow a strict folder layout where each skill is a standalone Markdown document containing sequential instructions, tool invocations, and compatibility constraints. Understanding how to structure the plugin manifest, author the [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files, and pass the validation pipeline is essential for contributing reliable capabilities to the Claude ecosystem.

## Core Architecture of a Skill-Based Claude Plugin

Every skill-based plugin in the community repository consists of three required components and two optional descriptors. The architecture enforces separation between plugin registration, skill definition, and runtime execution.

### The Plugin Manifest

The [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) file registers the plugin with Claude. Located at [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json), this JSON file declares the plugin’s name, version, whether it requires an MCP connection, and the complete list of skills it exposes. For example, the **QuickDesign** plugin defines its metadata and skill registry in [`quickdesign/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/plugin.json).

### The Skill Directory

Each skill resides in its own folder under the plugin’s `skills/` tree, such as `skills/{skill-name}/`. This directory contains:

- [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) – The human-readable workflow definition with YAML front-matter specifying the skill’s name, description, and compatibility constraints.
- `.version` – An optional marker file tracked by the CI pipeline to detect changes.
- `references/` – Optional subfolder for reusable markdown assets like validation rules or model-specific guidance.

The **Tres Finance** wallet upload skill demonstrates this structure in [`tres-finance-plugin/skills/tres-wallets-upload/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-wallets-upload/SKILL.md), where it orchestrates file parsing, validation, and batch MCP mutations through explicit sequential steps.

### The Marketplace Descriptor (Optional)

For plugins published to the Claude Marketplace, the [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) file at [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) supplies display metadata including icons, pricing, and extended descriptions. The QuickDesign plugin includes a complete example in [`quickdesign/.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/marketplace.json).

## Defining a New Skill in the Claude Plugin Repository

Creating a skill requires strict adherence to the repository’s conventions to ensure the validation pipeline passes and the runtime executes steps deterministically.

### 1. Initialize the Directory Structure

Create a folder hierarchy that separates plugin configuration from skill implementations:

```text
my-plugin/
  .claude-plugin/
    plugin.json
    marketplace.json
  skills/
    my-skill/
      SKILL.md
      .version
      references/
        rules.md

```

### 2. Author the SKILL.md File

Every [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) begins with YAML front-matter declaring the skill’s identity and requirements:

```yaml
---
name: my-skill
description: >-
  Short, one-sentence summary of what the skill does.
compatibility: "Optional prerequisite (e.g. MCP connection)"
---

```

Below the front-matter, write the workflow as a sequential checklist. The Claude-MCP runtime enforces a **hard gate** between steps, meaning Claude cannot proceed to Step 1 until Step 0’s instructions complete. Use built-in tool verbs such as `ask_user_input_v0` for user prompts, `show_widget` for UI components, or raw GraphQL mutations for MCP interactions.

For example, a minimal greeting skill defines two explicit steps:

```markdown

## Step 0 — Greet the user

Ask the user for their name using `ask_user_input_v0`:
question: "What is your name?"
type: single_input

## Step 1 — Confirm greeting

Show a plain-text message:
Hello, {{user_input}}! Nice to meet you.

```

### 3. Update the Plugin Manifest

Register the new skill by adding its name to the `skills` array in [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json):

```json
{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "A plugin demonstrating skill-based architecture.",
  "requiredMcp": false,
  "skills": [
    "my-skill"
  ]
}

```

The **ELI5** plugin provides a minimal working example of this manifest structure in [`eli5/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/eli5/.claude-plugin/plugin.json).

### 4. Validate Through the CI Pipeline

Before submitting, ensure the skill passes the automated checks defined in [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml). This workflow verifies that every [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) contains proper YAML front-matter, confirms GraphQL query syntax where present, and validates that version files exist for tracked skills.

## Runtime Execution Model

When Claude receives a user request matching a skill’s description, the runtime loads the corresponding [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) and executes the workflow:

1. **Parse** – The runtime reads the YAML front-matter to confirm compatibility constraints (e.g., required MCP connections).
2. **Execute** – Claude processes steps in strict order, invoking tools like `ask_user_input_v0` or `show_widget` only when explicitly called.
3. **Integrate** – The runtime performs external calls such as schema introspection or MCP mutations as specified in the skill.
4. **Respond** – Claude returns a tidy plain-text or markdown summary to the user, never raw HTML unless a widget is explicitly requested.

This design guarantees **deterministic, auditable flows** and prevents accidental step-skipping during complex multi-stage operations.

## Practical Code Examples

### Complete Plugin Manifest

```json
{
  "name": "example-plugin",
  "version": "0.1.0",
  "description": "A demo plugin with a single hello-world skill.",
  "requiredMcp": false,
  "skills": [
    "hello-world"
  ]
}

```

### Skill with References

For complex skills requiring external validation rules, store reusable markdown in the `references/` subfolder and link to it from the main [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md). The **QuickDesign** CLI skill demonstrates this pattern by importing voice-continuity guidelines from [`quickdesign/skills/quickdesign/references/voice-continuity.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/references/voice-continuity.md).

## Summary

- A **skill-based Claude plugin** consists of a JSON manifest at [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) and one or more Markdown skill definitions under `skills/{name}/SKILL.md`.
- Each [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) requires YAML front-matter specifying `name`, `description`, and optional `compatibility` constraints.
- Workflows execute sequentially with **hard gates** between steps, using tools like `ask_user_input_v0` and `show_widget` for user interaction.
- The repository CI pipeline in [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml) checks front-matter validity, GraphQL syntax, and version tracking.
- Optional marketplace metadata resides in [`.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json) for published plugins.

## Frequently Asked Questions

### What is the difference between a Claude plugin and a skill?

A **plugin** is the container registered with Claude through [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json), while a **skill** is a specific reusable workflow defined within that plugin. A single plugin can expose multiple skills—for example, the Tres Finance plugin might contain separate skills for wallet uploads, transaction history, and balance queries, each with its own [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) file.

### Does every skill-based Claude plugin require an MCP connection?

No. The [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) manifest includes a boolean `requiredMcp` field that indicates whether the plugin needs an active Model Context Protocol connection. Skills can operate entirely within Claude’s native capabilities using tools like `ask_user_input_v0` and `show_widget`, or they can interact with external services via MCP when `requiredMcp` is set to `true` and the appropriate `compatibility` constraints are listed in the skill’s front-matter.

### How does the validation pipeline ensure skill quality?

The [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml) CI workflow automatically checks every [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) for proper YAML front-matter syntax, validates that referenced GraphQL queries are syntactically correct, and ensures `.version` files are present for skills tracked by the repository. This prevents malformed skills from merging into the main branch and guarantees consistent runtime behavior.

### Can skills reference external documentation or validation rules?

Yes. Skills can import auxiliary markdown files stored in a `references/` subfolder within the skill directory. For instance, the QuickDesign skill imports domain-specific guidelines from [`quickdesign/skills/quickdesign/references/voice-continuity.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/references/voice-continuity.md). These references allow you to maintain reusable validation regexes, style guides, or model-specific instructions that multiple steps—or even multiple skills—can share without duplicating content.