Claude Plugins Skill File Size Limits: Complete Technical Guide

Skill files in the Claude Plugins Community repository must stay under 1 MiB individually and 5 MiB total per plugin, enforced by validation scripts in .github/actions/validate-plugins/.

The anthropics/claude-plugins-community repository hosts community-contributed Claude skills defined in SKILL.md files. These markdown documents power Claude's plugin functionality, but the repository enforces strict size limitations to prevent runtime performance degradation. Understanding these constraints is essential for plugin developers submitting to the community marketplace.

---

Individual Skill File Limit: 1 MiB Maximum

Each SKILL.md file cannot exceed 1 MiB (1,048,576 bytes). The validator checks this using stat -c%s and aborts on oversized files.

In .github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh, the validation pipeline reads each skill file's byte count and fails the build if any single file exceeds this threshold. This prevents Claude from loading excessively large markdown documents into memory during skill execution.

---

Aggregate Plugin Limit: 5 MiB Total

The total size of all skill files within a plugin directory must stay under 5 MiB (5,242,880 bytes). The same validation script aggregates SKILL.md sizes across the plugin and enforces this ceiling.

This protects against plugins containing numerous medium-sized skills that collectively burden the runtime. Developers must audit their entire plugin bundle, not just individual files.

---

Line Length Constraint: 2,000 Characters

A secondary limit affects parsing: individual lines longer than 2,000 characters are truncated. As documented in .github/actions/validate-plugins/scripts/40-validate-cli-local.sh, the read-file utility used by the validator applies this truncation, which can corrupt skill definitions with long inline data or minified scripts.

---

Workarounds for Large Skill Requirements

When your use case naturally demands substantial content, split the logic across multiple files rather than inflating SKILL.md:

• Extract heavy processing to helper scripts referenced by concise skill steps
• Store large data assets externally and fetch them via API calls
• Modularize across multiple focused skills instead of one monolithic definition

---

Example: Compliant Skill File Structure

# SKILL.md

name: large-report-generation
description: "Generate detailed reports; heavy logic lives in helper scripts."
trigger:
  - "create detailed report"
steps:
  - name: Execute report generator
    command: python scripts/generate_report.py --output report.xlsx
  - name: Upload results
    command: curl -X POST -F file=@report.xlsx {{upload_endpoint}}
  - name: Confirm completion
    output: "Report generated and uploaded successfully."

This pattern keeps SKILL.md minimal (≈150–300 KB typical) while delegating substantial work to external scripts that aren't subject to skill file size limits.

---

Summary

• 1 MiB per skill file — enforced by stat -c%s in 20-validate-cli-marketplace.sh
• 5 MiB total per plugin — aggregated across all SKILL.md files in a plugin directory
• 2,000 characters per line — truncation threshold in 40-validate-cli-local.sh
• Exceeding any limit causes validation failure and prevents marketplace submission
• Large logic belongs in external scripts, not inline in skill definitions

---

Frequently Asked Questions

What happens if my SKILL.md exceeds 1 MiB?

The GitHub Actions validation pipeline in .github/actions/validate-plugins/scripts/20-validate-cli-marketplace.sh detects the oversized file and fails the build. Your plugin cannot merge until you reduce the file size, typically by extracting content to helper scripts.

Does the 5 MiB limit include non-skill files like Python scripts?

No. The 5 MiB aggregate limit applies only to SKILL.md files within the plugin directory. Helper scripts, configuration files, and other assets don't count toward this total, making external script references the recommended pattern for substantial functionality.

Why does the validator truncate lines at 2,000 characters?

The read-file utility's 2,000-character truncation, as noted in .github/actions/validate-plugins/scripts/40-validate-cli-local.sh, prevents parser memory issues with extremely long lines. This typically affects minified JSON, base64-encoded data, or inline scripts. Store such data in separate files and reference them instead.

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