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

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 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 file registers the plugin with Claude. Located at .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.

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 – 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, 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 file at .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.

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:

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 begins with YAML front-matter declaring the skill’s identity and requirements:

---
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:

## 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:

{
  "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.

4. Validate Through the CI Pipeline

Before submitting, ensure the skill passes the automated checks defined in .github/workflows/validate-plugins.yml. This workflow verifies that every 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 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

{
  "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. The QuickDesign CLI skill demonstrates this pattern by importing voice-continuity guidelines from quickdesign/skills/quickdesign/references/voice-continuity.md.

Summary

• A skill-based Claude plugin consists of a JSON manifest at .claude-plugin/plugin.json and one or more Markdown skill definitions under skills/{name}/SKILL.md.
• Each 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 checks front-matter validity, GraphQL syntax, and version tracking.
• Optional marketplace metadata resides in .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, 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 file.

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

No. The 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 CI workflow automatically checks every 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. 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.

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