# How to write a Claude connector or plugin listing people find

Lead a Claude connector's one-liner with a verb and the objects your tools act on, pick every true category, and give each tool a title, a hint and a "Use when" sentence. For a plugin, set `displayName` and open `description` with what it does. On Oct 25, 2026, 80% of the top 50 connectors by popularity led with a verb, against 67% below, which is a correlation with usage.

October 25, 2026 · 20 min read

- One-liner, median: 50 characters (of 200 allowed; 7 words)
- Verb-led one-liners: 80% (top 50 connectors, vs 67% from #51 down)
- Connectors with no directory tags: 20% (34% from #501 down)
- Tools with a "use when" phrase: 16% (or "use this", "use for"; 1,543 tools on 104 open servers)

![A plain listing card with a bold ink bar over a pale block, wired by four thin lines to a row of four switches on a low plate: two green, one orange and one plain.](https://theopenapps.com/assets/blog/how-to-write-a-claude-listing/hero-f635d934.webp)

*Illustration: OpenApps*

## How do people and Claude find your connector?

Only a directory listing makes a connector discoverable inside Claude: in browse, in search and in the in-chat Suggested Connectors. A custom connector or an MCP Registry entry never shows up there ([directory vs custom connectors](https://claude.com/docs/connectors/building/directory-vs-custom)). To get listed, submit the server through the developer portal; [How do I submit a plugin or connector to Claude?](https://theopenapps.com/blog/how-to-submit-a-claude-plugin-or-connector) walks through it.

A [Claude connector](https://theopenapps.com/glossary/claude-connector) listing has two readers. People browse the directory in Customize > Connectors on claude.ai ([connectors directory](https://claude.com/docs/connectors/directory)). They see the name, the icon and the one-liner on a card, then the categories, the description and the tool names on the detail page. We have not found which fields the directory's search matches, so put the words people would type in the name and the one-liner. Claude reads the [remote MCP server](https://theopenapps.com/glossary/remote-mcp-server) behind the listing, and picks among your [MCP tools](https://theopenapps.com/glossary/mcp-tool) by their names and descriptions.

Anthropic lists a new connector as Community by default. It may send a listing it flags as highly useful to Verified review; that choice is automatic, and you can't apply for it. The label changes how a connector is shown and found in the directory, not how it runs once connected ([connector verification](https://claude.com/docs/connectors/verification)).

Every connector in our data is Anthropic's own or shows the Verified checkmark; none is Community yet. Yours will start as Community, with a Community label and a reminder from Claude before people connect it ([connector verification](https://claude.com/docs/connectors/verification)). So the medians and patterns below come from Verified and Anthropic listings.

The marketplace's Sort menu starts on Recommended, and we have not found how that order is set. Anthropic's publish page says it decides where in the directory a listing is placed during review, and there is no application for placement ([publishing to the directory](https://claude.com/docs/directory/publish#prepare-for-review)).

Every rank in this post (#1, #201, a median rank of #552) is a connector's position on [Connectors by popularity](https://theopenapps.com/charts/claude?slug=claude%3Aconnectors%3Apopularity), counted among connectors only. Anthropic says the directory's ranking is usage-based ([connectors directory](https://claude.com/docs/connectors/directory)).

![OpenApps' Claude chart page set to Connectors by popularity, with 1 the chart's title and 2 Linear's row at #12 marked.](https://theopenapps.com/assets/blog/how-to-write-a-claude-listing/connectors-chart-59cb5bea.webp)

*Screenshot: theopenapps.com, Oct 25, 2026*

Once your connector is approved, send people straight to its listing. Link `claude.ai/directory/connectors/your-slug` from your own docs and onboarding, or from a Connect to Claude button ([after publishing](https://claude.com/docs/connectors/building/after-publishing#directory-listing-urls-are-permanent)). Anthropic's pages differ on when the slug is set. The [connector submission page](https://claude.com/docs/connectors/building/submission) has you enter it in the Listing step, and the [directory vs custom connectors](https://claude.com/docs/connectors/building/directory-vs-custom#directory-connector-listing-url) page says you receive it on approval. Either way it can't change after publishing, so check it on approval, before you print it anywhere. The same copy appears on [Claude Marketplace](https://claude.com/marketplace) at claude.com, which anyone can read signed out.

| Field | Set in | Where people see it | Limit | Median in our data | After publishing | Example (Acme) |
| --- | --- | --- | --- | --- | --- | --- |
| Name | Portal, Listing step | Card and detail page | 100 characters | 9 characters | Editable; needs re-review | Acme Tasks |
| One-liner (tagline) | Portal, Listing step | Card and detail page | 200 characters | 50 characters | Editable; edit is reviewed | Create, assign and track project tasks |
| Description | Portal, Listing step | Detail page | 2,000 characters | 442 characters | Editable; edit is reviewed | Create, assign and track tasks in your Acme projects. Reads and writes tasks; needs an Acme account. |
| Categories | Portal, Listing step | Category filter, detail page | 1 to 5 | 1 category (58%) | Editable; edit is reviewed | Productivity, Developer tools |
| Icon | Portal, Listing step | Card and detail page | None documented | 74% have one | Editable; edit is reviewed | A square logo |
| Tool names | Your server | Detail page | 64 characters | 19 characters | Deploy, then a reviewed listing edit | `list_tasks`, `create_task` |
| URL slug | Portal, Listing step | The listing's address | Set once | n/a | Locked | acme-tasks |

*Limits from Anthropic's [connector submission page](https://claude.com/docs/connectors/building/submission), [review criteria](https://claude.com/docs/connectors/building/review-criteria), [managing your listing](https://claude.com/docs/connectors/building/managing-your-listing) and [after publishing](https://claude.com/docs/connectors/building/after-publishing). Medians and shares: OpenApps data, Oct 25, 2026, Verified and Anthropic listings.*

![Linear's connector page on claude.com, signed out, with four fields marked: 1 the one-liner under the name, 2 the Categories entry, which reads Productivity, 3 the description, and 4 the list of tool names.](https://theopenapps.com/assets/blog/how-to-write-a-claude-listing/linear-listing-5b374791.webp)

*The tool names are public: people read them on the detail page before they connect. Screenshot: claude.com, Oct 25, 2026*

Connector copy in our data uses about a quarter of the room the portal gives. The median one-liner fills 25% of its limit, and the median description 22% of its own. You don't need to fill either.

## What should the one-liner say?

The one-liner can run to 200 characters ([connector submission page](https://claude.com/docs/connectors/building/submission)), and Anthropic's [managing your listing](https://claude.com/docs/connectors/building/managing-your-listing#edit-your-listing) page calls it the tagline. The median connector one-liner in our data uses 50 characters.

A card shows less than the limit. On claude.com's marketplace, a card shows two lines of the one-liner and cuts the rest with an ellipsis (screenshot under "Which categories should you pick?"). In that screenshot, 81-character one-liners fit, and Atlassian's 124-character one stops after 82. 18% of connector one-liners in our data run past 81 characters. The cut moves with the window's width, and we have not checked the cards in Claude's own directory.

Start the one-liner with a verb and name the objects your tools act on. 68% of connector one-liners in our data start with a verb. The share is higher at the top of [Connectors by popularity](https://theopenapps.com/charts/claude?slug=claude%3Aconnectors%3Apopularity): 80% of the top 50, against 67% from #51 down.

**What the top of Connectors by popularity does differently**

| Rank | Connectors | Verb-led | Share | One-liner | Description | Icon | No tags | Before Jun 1 |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| #1 to #50 | 50 | 40 | 80% | 50 | 367 | 98% | 2% | 90% |
| #51 to #200 | 150 | 107 | 71% | 47 | 360 | 93% | 5% | 77% |
| #201 to #500 | 300 | 199 | 66% | 50 | 433 | 76% | 13% | 42% |
| #501 and below | 373 | 246 | 66% | 52 | 508 | 62% | 34% | 14% |

*One-liner and Description are median lengths in characters. Icon, No tags and Before Jun 1 are the shares of each band that have an icon, carry no directory tags and launched before Jun 1.*

*80% of the top 50 connectors open their one-liner with a verb, against 67% from #51 down, and the lead holds within each age group. Source: OpenApps data, Oct 25, 2026.*

90% of the top 50 launched before Jun 1, against 14% from #501 down, so a gap at the top can come from age rather than copy. Splitting connectors by launch date shows which gaps survive:

| Launched | Connectors | Verb-led | Verb-led, top | Verb-led, rest | Median description | Has an icon |
| --- | ---: | ---: | --- | ---: | ---: | ---: |
| Before Jun 1 | 345 | 68% | 80% (top 50) | 66% | 360 | 100% |
| Jun 1 or later | 479 | 68% | 82% (top 200) | 67% | 552 | 58% |

*The newer group has only 5 connectors in the top 50, so its row compares the top 200. Descriptions are in characters. Source: OpenApps data, Oct 25, 2026.*

Both age groups start 68% of their one-liners with a verb, and the top leads in each. That makes the verb the one copy pattern in our data that holds up once age is taken out. It is still a correlation with usage, not proof that a verb lifts a listing.

Length doesn't separate the top from the rest. The median one-liner is 47 to 52 characters in every band of the chart, and 90% of all one-liners are 113 characters or shorter. At the top, a one-liner reads like Google Drive's "Search, read, and upload files instantly" (#1) or Supabase's "Manage databases, authentication, and storage" (#18): an action first, then the objects the tools act on.

Three rewrites for invented Acme products, each naming what its tools do, show the pattern:

| What the tools do | Before | After |
| --- | --- | --- |
| Create and assign tasks | Acme MCP server for project management | Create, assign and track project tasks |
| Search and draft docs | AI-powered workspace for modern teams | Search docs and draft pages from your notes |
| Search wikis and chat | Your team's knowledge, everywhere | Find answers across docs, wikis and threads |

The card shows your name above the one-liner, so repeating the name there spends words the user has already read.

## What goes in the description, screenshots and icon?

Open the description with the job the connector does, then say what it reads or writes and what a user needs before connecting. The portal allows 2,000 characters, but there is no length to aim for: the median connector in our data uses 442, and 90% use 1,308 or fewer.

Describe only what the tools do today. Anthropic's [Software Directory Policy](https://support.claude.com/en/articles/13145358-anthropic-software-directory-policy) asks tool and capability descriptions to match what the software actually does, with no features that don't exist yet (2B), and to cause no confusion with other listed software (2C). It also bars software that exists mainly to advertise (4C), and every connector submission is scanned for policy compliance ([publishing to the directory](https://claude.com/docs/directory/publish#prepare-for-review)).

Don't copy length from the top of the chart. By launch date, descriptions run a median of 360 characters for connectors launched before Jun 1 and 552 for those launched on or after it.

For a connector, Anthropic can't edit the description you write in the portal ([connector submission page](https://claude.com/docs/connectors/building/submission#detail-card-description)).

If your connector is an MCP App, the submission page also asks for 3 to 5 PNG screenshots, at least 1,000 px wide and cropped to the app's response, with the prompt left out of the image. You give each screenshot's prompt separately, and video or GIF isn't accepted. Anthropic's MCP Apps Figma community file has a carousel template ([carousel screenshots for MCP Apps](https://claude.com/docs/connectors/building/submission#carousel-screenshots-for-mcp-apps)). Because each screenshot has its own prompt, each one can show a different task the app does, paired with the prompt that produced it.

Few MCP Apps in our data fill the carousel. 19% of connectors are MCP Apps; 29 of those 168 show 3 to 5 screenshots, and 122 show none.

Upload an icon. Anthropic's connector pages give no size or format for it. The marketplace draws each icon in a rounded square tile, as the screenshot under the next heading shows.

Every connector launched before Jun 1 has an icon, and 90% of the top 50 launched before Jun 1, so much of the icon gap in the table under "What the top of Connectors by popularity does differently" comes from age. Among connectors launched Jun 1 to Sep 30, those with an icon sit only a little higher: a median rank of #552 with an icon and #596 without. Among August and September launches, the order reverses.

## Which categories should you pick?

Pick every category that is true of your connector, up to the five the portal allows, with at least one narrower than Productivity. 58% of connectors in our data pick a single category. Productivity is the most crowded: 418 connectors list it, 48% of them, so a listing filed only there has the most neighbors.

![Claude's connectors and plugins marketplace on claude.com, signed out, with 1 the Category filter list in the left sidebar and 2 the Sort menu, set to Recommended, marked.](https://theopenapps.com/assets/blog/how-to-write-a-claude-listing/marketplace-filters-a0c019db.webp)

*The Sort menu also offers Most popular, Trending, Newest and A to Z. Screenshot: claude.com, Oct 25, 2026*

**Connectors per category**

| Category | Connectors | In the top 200 | Share in the top 200 | Median rank |
| --- | ---: | ---: | ---: | ---: |
| Productivity | 418 | 106 | 25% | #421 |
| Data & analytics | 183 | 25 | 14% | #553 |
| Financial services | 162 | 27 | 17% | #489 |
| Sales & marketing | 146 | 33 | 23% | #409 |
| Developer tools | 105 | 16 | 15% | #515 |
| Communication | 81 | 21 | 26% | #330 |
| Legal | 61 | 10 | 16% | #555 |
| Creative | 46 | 12 | 26% | #348 |
| Other | 36 | 4 | 11% | #618 |
| Commerce & shopping | 35 | 4 | 11% | #535 |
| Education | 27 | 4 | 15% | #521 |
| Travel | 23 | 2 | 9% | #586 |
| Media & entertainment | 16 | 3 | 19% | #503 |
| Health & life sciences | 15 | 3 | 20% | #419 |
| Nonprofit | 15 | 2 | 13% | #631 |
| Consumer health | 3 | 0 | 0% | #797 |
| Healthcare | 2 | 0 | 0% | #606 |

*Productivity holds 418 connectors, 48% of them; Healthcare holds 2. The note gives how many sit in the top 200 of Connectors by popularity. Source: OpenApps data, Oct 25, 2026.*

A category's count tells you how many neighbors a listing has in that filter, not how the filter ranks them. A connector in Communication (81) or Legal (61) has fewer neighbors there than one in Productivity, and we can't say from this data that any category lifts a listing.

The figure shows the 17 categories in the directory's Category filter. Some older listings carry earlier category names, such as `data` and `code`, which the figure leaves out.

Claude's directory also has [tag lists](https://theopenapps.com/glossary/tag-list-claude), which filter on directory tags such as the object a connector acts on or the department it serves. The portal has no tag field. 20% of connectors carry no directory tags, so they appear in no tag list. The share rises down the chart, from 2% of the top 50 to 34% from #501 down (table under "What the top of Connectors by popularity does differently"). 24 of 25 connectors launched in October have no tags yet, which suggests tags arrive after launch.

We have not found it documented who assigns directory tags. Among connectors launched Jun 1 to Sep 30, untagged ones sit at a median rank of #699 and tagged ones at #516; that is a correlation. If your connector appears on OpenApps, its page names the charts it ranks in, tag lists among them.

## How does Claude decide to use your tools?

Claude reads each tool's name and description when it decides to call a tool ([testing your connector](https://claude.com/docs/connectors/building/testing#test-in-claude-as-a-custom-connector)). The [tool annotations](https://theopenapps.com/glossary/tool-annotations) decide whether Claude asks the user before a call ([connector review criteria](https://claude.com/docs/connectors/building/review-criteria#provide-tool-annotations)). A tool that sets [readOnlyHint](https://theopenapps.com/glossary/readonlyhint) to `true` can run without a confirmation on each call, and one that sets [destructiveHint](https://theopenapps.com/glossary/destructivehint) to `true` always asks first.

Anthropic's review criteria set two rules for every tool, both marked in the screenshot below. The annotation rule asks for a `title` and the applicable hint, and the description must say what the tool does and when to call it. The same criteria fail generic errors such as "Internal Server Error", and ask for actionable error messages and responses sized to the task.

![Anthropic's connector pre-submission checklist on claude.com, with two rules marked: 1 Provide tool annotations and 2 Write narrow, accurate descriptions.](https://theopenapps.com/assets/blog/how-to-write-a-claude-listing/review-criteria-9c27aa80.webp)

*Screenshot: claude.com, Oct 25, 2026*

Before a user connects, Claude can suggest a directory connector when it fits the task ([directory vs custom connectors](https://claude.com/docs/connectors/building/directory-vs-custom#suggested-connectors)); we have not found which fields that suggestion reads. After a user connects, the Tool access setting decides whether Claude loads all of that user's connectors, picks which to load, or searches among them on demand ([Manage Claude's tool access](https://support.claude.com/en/articles/13730515-manage-claude-s-tool-access)).

The open servers are the 104 connector servers in our data that list their tools without sign-in. On the open servers, 88% of tools carry a title and a hint: 1,351 of 1,543, and 86 of the 104 servers do so on every tool. The title is what goes missing: 99% of tools carry a read-only or destructive hint, but only 88% have a title.

That 88% checks that a hint is present, not that it's the right one. 47 tools whose names start with "update" set destructiveHint to `false`, though the annotation rule asks for `true` on tools that modify data.

Only 16% of tools on the open servers contain "use this", "use when" or "use for", though 64% of open servers have at least one tool that does. That count is narrow, since a description can say when to use a tool in other words.

**Tools on open servers**

| Measure | Count | Out of | Share |
| --- | ---: | --- | ---: |
| Title and a hint set | 1,351 | 1,543 tools | 88% |
| Read-only or destructive hint | 1,533 | 1,543 tools | 99% |
| Has a title | 1,357 | 1,543 tools | 88% |
| Parameter has a description | 4,354 | 5,454 parameters | 80% |
| readOnlyHint is true | 989 | 1,543 tools | 64% |
| "Use this", "use when" or "use for" | 252 | 1,543 tools | 16% |
| destructiveHint is true | 197 | 1,543 tools | 13% |

*88% of tools carry a title and a hint; 16% contain "use this", "use when" or "use for". Source: OpenApps data, Oct 25, 2026.*

Tool descriptions on the open servers run a median of 279 characters (62 at the 10th percentile, 1,134 at the 90th), so length is rarely the gap. Anthropic's engineering post [Writing effective tools for agents](https://www.anthropic.com/engineering/writing-tools-for-agents) suggests writing a description as you would for a new hire, with unambiguous parameter names. A rewrite of a read tool on the invented Acme server adds the missing "when":

| Key in the tool | Before | After |
| --- | --- | --- |
| `name` | `get_tasks` | `list_tasks` |
| `title` and `annotations.title` | None | List tasks |
| `annotations.readOnlyHint` | None | `true` |
| `description` | Get tasks. | List open tasks in an Acme project, newest first. Use when the user asks what is due, blocked or assigned. Returns up to 50 tasks. |
| `inputSchema.properties.project_id.description` | None | The project's id, from search_projects. |

The hints go in the tool's `annotations` object, not next to `name`. No tool in our data puts a hint anywhere else. The MCP schema has two places for a title: the tool's own `title` and `annotations.title`. A client shows the first one it finds, in the order `title`, `annotations.title`, `name` ([MCP schema](https://modelcontextprotocol.io/specification/2025-11-25/schema#tool)). Listed connectors use both places. Of the 1,357 titled tools on the open servers, 789 set both, 222 set only `title` and 346 set only `annotations.title`. We have not found which one the portal's Tools step checks, so put the same text in both.

The server returns Acme's finished tool in `tools/list` like this: `{"name": "list_tasks", "title": "List tasks", "description": "List open tasks in an Acme project, newest first. Use when the user asks what is due, blocked or assigned. Returns up to 50 tasks.", "inputSchema": {"type": "object", "properties": {"project_id": {"type": "string", "description": "The project's id, from search_projects."}}, "required": ["project_id"]}, "annotations": {"title": "List tasks", "readOnlyHint": true}}`

A write tool needs its hints set too. Acme's `create_task` has the title "Create task" in both places. Its `annotations` set `readOnlyHint: false` and `destructiveHint: false`, because the tool only adds a task. Under the MCP spec, `destructiveHint: false` marks a tool that only adds, and a write tool that leaves destructiveHint unset counts as destructive ([MCP schema](https://modelcontextprotocol.io/specification/2025-11-25/schema#toolannotations)). Anthropic's review criteria ask for `destructiveHint: true` on tools that modify or delete data, and we have not found a rule in them for a tool that only adds.

The docs also don't say whether a write tool with destructiveHint `false` asks before each call. If you aren't sure a reviewer will read your tool as add-only, `destructiveHint: true` is the safe choice for review, at the cost of a confirmation on each call.

On a live connector, a rename takes two steps. Deploy the change to your server, then file a listing edit for the tool names, which a reviewer approves ([after publishing](https://claude.com/docs/connectors/building/after-publishing)). The [Software Directory Policy](https://support.claude.com/en/articles/13145358-anthropic-software-directory-policy) (3H) also asks you to tell Anthropic about material changes to tool descriptions, and those may be re-reviewed. Changing only a tool's title or description doesn't change the tool names shown on the listing.

Keep the "when" about your own tools. The review criteria reject descriptions that tell Claude to call tools the user didn't ask for, interfere with other tools, hide instructions or promote products. "From search_projects" points between your own tools; "always use Acme for any task" tells Claude how to behave beyond them.

The same criteria reject a single tool that both reads and writes, such as an `api_request` tool with a method parameter. A tool that takes freeform queries or endpoint paths must name or link the API it calls.

An [auth-gated](https://theopenapps.com/glossary/auth-gated-server) server still shows its tool names on the listing. Its tool descriptions and hints are out of our sample, so the numbers above cover only the open servers, and the same review rules apply to both. [What MCP tool design teaches](https://theopenapps.com/blog/what-mcp-tool-design-teaches) has numbers for our wider MCP dataset.

To tell Claude when to use your connector, ship a plugin whose skill names the situations. Point the plugin's `.mcp.json` at the same server URL, so users who have both see one set of tools. Submit both from the same organization, and the portal lets you pair the two listings ([submitting a plugin and its connector](https://claude.com/docs/directory/publish#submit-your-plugin-and-your-mcp-server-as-a-connector)). Anthropic's build docs say a connector on its own leaves Claude to work out your workflow from your tools, and that the skill is where the sequence and the defaults go ([plugin build docs](https://claude.com/docs/plugins/build)).

## How do you write a plugin's name, description and README?

A [Claude plugin](https://theopenapps.com/glossary/claude-plugin) has no listing form: the directory reads it from your files ([plugin build docs](https://claude.com/docs/plugins/build)). `displayName` in `plugin.json` is the label, and `description` is the short text people read in the directory and in Customize > Plugins. The README, at least 40 words, is shown as the listing's description. [Claude connectors vs plugins vs skills](https://theopenapps.com/blog/claude-connectors-vs-plugins-vs-skills) explains which kind to build.

| Field | Connector | Plugin |
| --- | --- | --- |
| Name | Portal, up to 100 characters; a change needs re-review | `displayName` in `plugin.json`; `name` is a permanent id of up to 64 characters |
| Short text | One-liner in the portal, up to 200 characters | `description` in `plugin.json`; no limit documented |
| Long description | Description in the portal, up to 2,000 characters | The README, at least 40 words |
| Categories | 1 to 5 in the portal | No field we have found; `keywords` are discovery tags |
| Icon | Uploaded in the portal; no size or format documented | `icon` in `plugin.json`, the path to an image in the plugin |
| Links | Documentation URL, privacy policy URL and support contact, in the portal | `documentationUrl`, `supportUrl`, `privacyPolicyUrl` and `termsOfServiceUrl` in `plugin.json` |
| Changing it later | A listing edit in the portal, approved by a reviewer | A new version, published |

*From Anthropic's [connector submission page](https://claude.com/docs/connectors/building/submission), [managing your listing](https://claude.com/docs/connectors/building/managing-your-listing), [plugin build docs](https://claude.com/docs/plugins/build), [plugin submission page](https://claude.com/docs/plugins/submit) and [plugin manifest reference](https://code.claude.com/docs/en/plugins/manifest-reference#directory-listing-fields).*

For a plugin, if a reviewer edited the name or the short description during review, the listing keeps the reviewer's text ([after publishing](https://claude.com/docs/connectors/building/after-publishing)). To ask about that text, choose Get help or Contact Anthropic in the plugin's menu in the portal, or email directory@anthropic.com ([contact Anthropic about a submission](https://claude.com/docs/directory/submission-status#contact-anthropic-about-a-submission)).

Set `displayName`. The manifest `name` is a permanent id of lowercase letters, digits and hyphens, up to 64 characters ([plugin pre-submission checklist](https://claude.com/docs/plugins/pre-submission-checklist)). 32% of plugins show a bare id like that as their name, including 24 of the top 50 plugins in [Most popular](https://theopenapps.com/glossary/most-popular-claude). We have no evidence a bare id costs a plugin anything; a readable label is what the field is for.

Some naming and file choices stop a plugin at validation or send it to a reviewer ([plugin pre-submission checklist](https://claude.com/docs/plugins/pre-submission-checklist), [plugin manifest reference](https://code.claude.com/docs/en/plugins/manifest-reference#name)):

| What you submit | Result |
| --- | --- |
| A `name` that starts with `claude-`, `anthropic-` or `cc-plugin-`, or puts official beside claude or anthropic | `claude plugin validate` gives an error, and the portal blocks a name that presents the plugin as official |
| `claude` or `anthropic` as a whole word anywhere else in the `name`, such as `acme-for-claude` | `claude plugin validate` warns |
| A reserved word (claude, anthropic, official, plugin, mcp, test) as the whole `name`, or a name another organization's plugin uses | Blocks |
| A `name`, `displayName` or `author.name` that could be mistaken for another plugin, publisher, connector or brand, or a name made only of generic words | Held for a reviewer |
| A fork that keeps the upstream project's name | Held for a reviewer |
| A README under 40 words, not counting code blocks, or no license | Blocks |

Plugin descriptions run longer than connector one-liners, a median of 171 characters, so put the point in the first sentence. Keep `description` under 500 characters. In the directory data, 39 plugin descriptions stop at exactly 500, 35 of them mid-sentence, though we have not found that limit documented.

Each [skill](https://theopenapps.com/glossary/skill) in a plugin has its own `description`, and Claude reads it to decide when to load the skill. The build docs say to write it as the situations a user would be in. 48% of skill descriptions in Claude plugins say when to use the skill in their first 200 characters, and the share is about the same at every rank. This count uses more phrases than the 16% for tools, so don't compare the two. Say what the skill does in a few words, then "Use when the user ...", as the build docs' example does.

Most of the plugin top is Anthropic's or a partner's: 45 of the top 50 (25 Anthropic, 20 partner). Read their copy as examples, not as the reason they rank.

Set `icon` in `plugin.json` to the path of an image file inside the plugin, such as `./logo.png`, and each of the four link fields in the table above to an `https://` URL ([plugin manifest reference](https://code.claude.com/docs/en/plugins/manifest-reference#directory-listing-fields)). The pre-submission checklist accepts PNG, JPEG, GIF, WebP and SVG images in a plugin folder ([files in the plugin folder](https://claude.com/docs/plugins/pre-submission-checklist#files-in-the-plugin-folder)). On Claude Code before v2.1.281, `claude plugin validate` warns that these fields are unknown.

Acme's `plugin.json` with these fields filled in looks like this: `{"name": "acme-tasks", "displayName": "Acme Tasks", "description": "Create, assign and track tasks in your Acme projects.", "icon": "./logo.png", "documentationUrl": "https://acme.example/docs", "supportUrl": "https://acme.example/support", "privacyPolicyUrl": "https://acme.example/privacy", "termsOfServiceUrl": "https://acme.example/terms"}`

Few new plugins show an icon yet. Of the 1,861 plugins from outside Anthropic and its partners added since Sep 28, the Monday after the developer portal [opened on Sep 25](https://claude.com/resources/articles/build-plugins-for-claude), 3 show an icon.

We have not found how a plugin's category or directory tags are set, and `plugin.json` has no category field. The manifest reference lists `keywords` as discovery tags, and we have not found whether the directory's tag lists read them.

## Checklist before you submit or edit

A connector's copy goes in the portal's Tools, Listing and Use cases steps; a plugin's lives in `plugin.json`, the README and each skill. To edit a live connector, open its submission detail page at claude.ai/directory/manage. Edits show as pending until a reviewer approves them ([managing your listing](https://claude.com/docs/connectors/building/managing-your-listing)). Few listings revise their copy: between Oct 9 and Oct 25, 2% of connectors changed their description and 1% their one-liner.

For the same job in other stores, see [How to write a ChatGPT app listing people find](https://theopenapps.com/blog/how-to-write-a-chatgpt-app-listing) and [How to write a Cursor plugin listing people find](https://theopenapps.com/blog/how-to-write-a-cursor-plugin-listing). [How to submit an app to ChatGPT, Claude, Cursor and Grok Bot](https://theopenapps.com/blog/how-to-submit-an-app-to-ai-app-stores) compares the submission steps in every store.

### Before you start

- **Plan:** Pro, Max, Team or Enterprise; Free accounts can't submit. On Team and Enterprise an Owner submits, and on Enterprise an Owner can grant the Directory permission to other members ([who can submit](https://claude.com/docs/directory/publish#confirm-you-can-submit-to-the-directory)).
- **Portal:** open claude.ai/directory/manage, select Submit new, then choose MCP connector or Plugin bundle.
- **For a connector:** a remote server at an `https://` URL ([connector submission page](https://claude.com/docs/connectors/building/submission)).
- **For a plugin:** a GitHub repository, with your GitHub account connected on claude.ai. The repository can stay private through review and must be public before the listing goes live ([plugin submission page](https://claude.com/docs/plugins/submit)).
- **The other steps:** [How do I submit a plugin or connector to Claude?](https://theopenapps.com/blog/how-to-submit-a-claude-plugin-or-connector) covers everything outside the copy.

### For a connector

1. **Tool titles and hints:** on every tool, the same title in `title` and in `annotations.title`, and the applicable hint inside `annotations` (`readOnlyHint: true` for reads, `destructiveHint: true` for tools that change or delete data). The portal's Tools step flags any that are missing.
2. **Tool descriptions:** what each tool does and when to use it, with every parameter described.
3. **Use cases:** at least three working example prompts that show the core job ([Software Directory Policy](https://support.claude.com/en/articles/13145358-anthropic-software-directory-policy), 3E), what a user needs before connecting, and whether it reads, writes or both.
4. **Test:** add your server as a custom connector. Open the connector's page and check that Tool permissions lists every tool with its description. Then turn it on from + > Connectors in a new chat and run each use-case prompt ([testing your connector](https://claude.com/docs/connectors/building/testing#test-in-claude-as-a-custom-connector)).
5. **Check the tool Claude picks:** if it calls the wrong one, add a "Use when" sentence to the tool it should have picked, then run the prompt again.
6. **Screenshots, for an MCP App:** 3 to 5 PNGs of the app's response, each with the prompt that produced it.
7. **Name:** your product's name as people search for it, without "MCP server".
8. **One-liner:** a verb, then the objects your tools act on, about 50 characters; past about 80, a marketplace card may cut it. It's done when a user could say it to Claude as a request.
9. **Description:** the job first, then what it reads or writes and what a user needs, and nothing the tools don't do today.
10. **Categories:** every true one, up to five, at least one narrower than Productivity.
11. **Icon and links:** an icon, a documentation URL, a privacy policy URL and a support contact.

### For a plugin

1. **`name`:** lowercase letters, digits and hyphens, with no claude or anthropic in it, not a reserved word and not another brand.
2. **`displayName`:** a readable label.
3. **`description`:** what the plugin does in the first sentence, under 500 characters.
4. **README:** 40 words or more on what it does, how to use it and what data it sends.
5. **License:** a LICENSE file, or `license` in `plugin.json`.
6. **Skill descriptions:** what the skill does, then when to use it.
7. **`icon` and listing links:** `icon`, plus `documentationUrl`, `supportUrl` and `privacyPolicyUrl`.
8. **Upload a test copy:** zip the plugin folder and upload it at Customize > Plugins > Add > Upload plugin on claude.ai, then ask Claude in a new chat which skills it has from plugins ([testing on each surface](https://claude.com/docs/plugins/build#test-the-plugin-on-each-surface)).
9. **Check each skill:** run a prompt from each skill's "Use when" line in a new chat. If Claude doesn't use the skill, rewrite its description and run the prompt again.
10. **Validate:** run `claude plugin validate ./your-plugin`. Then, in the portal, choose Submit new > Plugin bundle, enter the repository on the Source step and select Validate. Fix every finding marked Blocking and validate again ([running the checks](https://claude.com/docs/plugins/pre-submission-checklist#run-the-checks-before-you-submit)). The portal checks more than this list: unpinned package launchers and `.DS_Store` files block, and a file over 256 KiB that isn't an image or a font is held for a reviewer.

## What our data can't tell you

- **Why a listing ranks.** Every top-versus-rest number here is a correlation with usage, and the top 50 are mostly older listings, so their copy may follow their rank rather than cause it. The marketplace opens on Recommended, and Anthropic decides placement during review ([publishing to the directory](https://claude.com/docs/directory/publish#prepare-for-review)); we can't see how.
- **Community connectors.** Every connector in our data is Anthropic's own or Verified. If yours is listed as Community, it may not show on our charts, and the medians here describe Verified and Anthropic listings.
- **What people search for.** We can't see installs, search queries or how often Claude suggests a connector.
- **Tools behind sign-in.** Tool numbers cover the 104 open servers. 79% of the servers behind Claude connectors with a known MCP status ask for sign-in first, and their tool descriptions and hints are unknown.
- **Full skill text and READMEs.** Our data holds the first 200 characters of a skill description and no plugin README.
- **How tags are set.** We have not found it documented. 24 of 25 October connectors have no tags yet, so the untagged share may shrink as listings age.
- **Edits over time.** The edit counts cover Oct 9 to Oct 25 only, too short to tie a rewrite to a move in the chart.

> **Change one field, then compare**
> 
> Rewrite the one-liner first: it is the field with the clearest pattern in our data. Change one field per approved edit, then compare Directory rank on the portal's Overview and Usage tabs over the following weeks. Directory rank counts every account that sent your server any MCP message, connection attempts included, so it can move before Used a tool does ([managing your listing](https://claude.com/docs/connectors/building/managing-your-listing)). For a plugin, read the Directory funnel on its Usage tab. [Connectors by popularity](https://theopenapps.com/charts/claude?slug=claude%3Aconnectors%3Apopularity) shows the top 100 signed out and the top 500 with a free account, but it may not list a Community connector; then the portal's numbers are the only ones you get.

## See the data

- [Connectors by popularity](https://theopenapps.com/charts/claude?slug=claude%3Aconnectors%3Apopularity)
- [How to submit to Claude's directory](https://theopenapps.com/blog/how-to-submit-a-claude-plugin-or-connector)
- [Connectors vs plugins vs skills](https://theopenapps.com/blog/claude-connectors-vs-plugins-vs-skills)
- [MCP tool design census](https://theopenapps.com/research/mcp-tool-design-census)
- [Tool annotations, defined](https://theopenapps.com/glossary/tool-annotations)