# Claude Plugin Descriptions: 7 Best Practices from the Anthropic Community Repository > Discover 7 best practices for Claude plugin descriptions from the Anthropic community repository. Learn to write clear, effective descriptions that drive user adoption and engagement. - Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community) - Tags: best-practices - Published: 2026-09-01 --- **The most effective Claude plugin descriptions begin with a concise one-sentence purpose, list key capabilities and API integrations, include specific trigger phrases, define scope exclusions, and explicitly state privacy practices—following patterns proven in the `anthropics/claude-plugins-community` repository.** Writing a compelling plugin description is not just marketing fluff—it directly impacts **discoverability**, **model triggering accuracy**, and **user trust**. In the `anthropics/claude-plugins-community` repository, the highest-quality plugins follow a consistent structural pattern that balances human readability with machine-friendly precision. This guide breaks down the seven best practices extracted from production-ready examples. --- ## Start with a Concise Purpose Statement The first sentence of your description must communicate the plugin's core function without ambiguity. The **TRES Finance plugin** demonstrates this perfectly: > "The first official TRES Finance plugin for Claude Code — blockchain accounting workflows, ledger management, and transaction analysis." This single line in [`tres-finance-plugin/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/plugin.json) accomplishes three things: identifies the plugin category, names the specific domain (blockchain accounting), and hints at primary capabilities. Avoid front-loading with technical implementation details or lengthy setup instructions. --- ## List Key Capabilities and Primary APIs After the purpose statement, enumerate the main actions your plugin enables. The **QuickDesign skill** in [`quickdesign/skills/quickdesign/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/skills/quickdesign/SKILL.md) provides a model example: ```markdown description: | Generate AI media — UGC promo videos, image edits, product creatives, video upscales — through Seedance, Kling, Sora2, Nano Banana, and GPT Image. ``` Note the pattern: **action verbs** (generate, edit, upscale) paired with **specific tool names**. This helps Claude's retrieval system match user intent to your plugin's actual functionality. Generic claims like "handles various media tasks" perform worse than explicit capability lists. --- ## Include Explicit Trigger Phrases The most discoverable plugins document the exact utterances that should activate them. The `tres-upload-tx-header-validation` skill in [`tres-finance-plugin/skills/tres-upload-tx-header-validation/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-upload-tx-header-validation/SKILL.md) implements this as a bulleted list within the description: - "fix my CSV headers" - "bulk transaction upload failed" - "missing required columns" ```yaml # Example: Skill description with trigger phrases description: | Validate and repair CSV headers for TRES Finance transaction uploads. Trigger phrases: "fix my CSV headers", "bulk transaction upload failed", "missing required columns". ``` These phrases train Claude's relevance model to surface your plugin when users express related needs—even with varying wording. --- ## Define Scope and Exclusions Explicitly Prevent accidental invocations by stating what your plugin **does not** do. The same TRES Finance CSV skill clarifies boundaries: > "This skill does **not** handle contacts import or wallet uploads." This exclusionary statement appears directly in [`tres-finance-plugin/skills/tres-upload-tx-header-validation/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/skills/tres-upload-tx-header-validation/SKILL.md). Explicit negative scope reduces false-positive triggers and manages user expectations before they attempt unsupported operations. --- ## Reference Privacy and Telemetry Practices User trust depends on transparent data handling. The repository's root [`README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/README.md) establishes a standard: ```markdown This plugin collects **no usage telemetry**. ``` For plugins requiring API keys or external services, disclose this explicitly. The **testdino plugin** in [`testdino/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/testdino/.claude-plugin/plugin.json) pairs minimal descriptions with clear configuration requirements: ```json { "name": "testdino", "description": "Run TestDino-powered test analysis directly in Claude Code. No data leaves your environment.", "userConfig": [ { "name": "TESTDINO_API_KEY", "description": "Your TestDino API key for test result analysis." } ] } ``` --- ## Use Plain Markdown Without Formatting Artifacts The Claude marketplace renders descriptions as plain markdown. Avoid these common mistakes: - **Backticks** for code terms (the renderer may display them literally) - **HTML tags** (stripped or garbled in display) - **Excessive markup** (bold, italics, headers within the description field) Keep descriptions as simple text paragraphs or minimal bullet lists. The [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) and [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files in the repository consistently follow this constraint. --- ## Respect Character Limits While Maintaining Completeness Platform constraints typically enforce **200–300 character limits** for summary descriptions, with extended fields available for detailed capability lists. Structure your content hierarchically: | Field | Purpose | Length Target | |-------|---------|---------------| | `description` (plugin.json) | One-sentence purpose | ~120 characters | | `description` (SKILL.md) | Capabilities, triggers, exclusions | ~300 characters | The **QuickDesign** example achieves this density without sacrificing clarity: ```markdown description: | CLI for AI media generation: UGC videos, image edits, product creatives, upscales via Seedance, Kling, Sora2, Nano Banana, GPT Image. ``` --- ## Complete Working Example Combine all practices into a production-ready template: ```json // plugin.json — top-level plugin description { "name": "weather-lookup", "description": "Add real-time weather lookup to Claude Code using OpenWeather API. No telemetry collected.", "repository": "https://github.com/your-org/weather-lookup", "userConfig": [ { "name": "OPENWEATHER_API_KEY", "description": "Your OpenWeather API key (obtain at https://openweathermap.org/api)" } ] } ``` ```markdown description: | Retrieve current weather conditions for any city worldwide. Trigger phrases: "what's the weather in [city]", "current temperature in [city]", "weather now in [city]". Capabilities: Temperature, humidity, wind speed, visibility, atmospheric pressure. Exclusions: Does not provide forecasts (use the `weather-forecast` skill), historical data, or severe weather alerts. ``` --- ## Summary Effective Claude plugin descriptions follow a proven structure derived from the `anthropics/claude-plugins-community` repository: - **Lead with purpose**: One sentence stating what the plugin does - **Enumerate capabilities**: Specific APIs and actions enabled - **Document triggers**: Exact phrases that should activate the skill - **Bound the scope**: Explicit statements about what is not supported - **Disclose privacy**: Clear telemetry and data handling statements - **Format plainly**: Simple markdown without HTML or backtick-heavy code - **Respect limits**: Concise summaries with extended detail where appropriate --- ## Frequently Asked Questions ### What makes a Claude plugin description different from general software documentation? Claude plugin descriptions serve dual audiences: human users browsing the marketplace and Claude's retrieval-augmented generation system selecting which skill to invoke. Unlike general documentation, they must include **trigger phrases** that match natural language queries and **scope exclusions** that prevent misfires. The `anthropics/claude-plugins-community` repository demonstrates that successful descriptions optimize for semantic search relevancy, not just readability. ### How long should a Claude plugin description be? Aim for **120 characters** for the core `description` field in [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) and **up to 300 characters** for skill-level descriptions in [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files. The TRES Finance and QuickDesign examples in the repository achieve completeness within these constraints by prioritizing action verbs, tool names, and trigger phrases over explanatory prose. ### Should I include API implementation details in the description? No. Reserve technical implementation details for documentation or configuration schemas. The description should answer **what** the plugin enables and **when** to use it, not **how** it works internally. The QuickDesign skill mentions external APIs (Seedance, Kling, Sora2) only as capability indicators, not architectural documentation. ### Where exactly should trigger phrases appear in a Claude plugin? Trigger phrases belong in the `description` field of **skill-level** [`SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/SKILL.md) files (located at `skills/{skill-name}/SKILL.md`), not in the top-level [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json). The [`tres-upload-tx-header-validation/SKILL.md`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-upload-tx-header-validation/SKILL.md) file provides the canonical example, embedding phrases directly in the description text where Claude's relevance system can index them for matching.