We wanted to fix that! This blog is the story of publishing a plugin that puts Elastic's capabilities where developers are already working. We already had the elastic/agent-skills repository, and we’ve both blogged about and documented them, but an official Claude plugin makes it that much easier for our customers to use those skills.

Getting here was a journey. Along the way, we learned a lot, and wanted to share our experience. 

It took us three weeks from first commit to live. Claude docs got us 80% of the way, the other 20% was undocumented review criteria and a versioning model that cuts a new release on every commit. There was limited visibility on when, or where, the plugin would appear.

Here’s what we learned:

Agent Skills versus a Claude plugin: Why we needed both

As we worked our way through all the reference materials, we realized that our Agent Skills were only part of what a Claude plugin can include. Although Agent Skills are a generic open standard, adopted by major agent vendors and ecosystems, a Claude plugin can contain much more; however, some of it may not be as generically applicable across platforms. One example from Claude Code Docs:

This contains quite a bit more than skills, and we want room to grow into those.

So we decided that we needed a new repo for our Claude plugin. That way, we’d have a home where all Claude-specific features could live, separate from our generic Agent Skills. Thus was born the elastic/claude-plugin repository.

Submitting a plugin to the Claude directory

Claude has thorough documentation, and I won’t rehash it all here, but for reference, you may want to read:

• Publish to the directory

• Plugin pre-submission checklist

• Build your first plugin

We went through the above and made sure that we addressed everything on the checklist. But when I tried to submit the plugin at https://claude.ai/directory/manage, I got the following message:

I’m an engineer. An individual contributor. I have no business being an “owner” of an account for a software tool used by most Elastic employees. But the IT team that owns it wouldn’t be maintaining and supporting this external-facing plugin. 

This was our first bit of friction, but it also led to our first lesson, namely, if you have a contact at Anthropic, make use of them. Elastic had already established a partnership with Anthropic, so when we hit this issue, we simply messaged our point of contact, who quickly got back to us:

Once we had the right permissions, it was relatively straightforward to fill out the submission form:

Despite the simplicity, this is where we made our first two mistakes.

Choosing your plugin path: Why not the repository root

As the screenshot above shows, this is the folder where Anthropic will look for your .claude-plugin/plugin.json. It’s also the root of what Anthropic’s automated systems will be scanning. 

We started with the default repository root for our plugin path, but this was a mistake, because the files for our own internal development purposes were also at the repository root. They included the CLAUDE.md that our engineers could use to maintain the plugin, along with our continuous integration (CI) pipelines, tests, and package-lock.json.

Scanning those files can lead to unexpected holdups during verification:

We should note that the Anthropic team didn’t let this be a blocker and, after manual review, waived these warnings.

Claude plugin versioning: Why we stopped pointing at main

There’s no single “right” way to version or release software. But at Elastic, we often stick to the following conventions:

• Development is done on feature branches (sometimes in forks).

• Pull requests (PRs) target main.

• Versioning uses SemVer (MAJOR.MINOR.PATCH).

• Releases are cut from release branches (MAJOR.MINOR) and tagged (vMAJOR.MINOR.PATCH).

On my initial read of Claude’s plugin versioning documentation, I knew that we’d need a different system for this repo. We only have one live version at once, rather than maintaining multiple majors and minors. So we planned to just use main with a specific version in the plugin metadata. We’d merge PRs into main, as normal, and when ready to release, we’d bump that version and create a Git tag. Easy.

But that’s not how it works:

That initial approach actually led to manyv0.0.1 “versions” of the plugin, one for each merge commit.

With help from our Anthropic contacts (the astute reader will notice that this is a theme), we got the following clarification:

After realizing this, we changed our plugin to point at a dedicated stable branch. Now we can merge to main as normal but only merge main into stable when we’re ready to release a batch of changes and update our version number. This results in our flow looking like:

What happens after you submit a Claude plugin

You wait.

When we first submitted, we saw only the following:

While we were in the process of writing this blog, Anthropic made some changes to its UI, providing a bit more visibility. Now the submissions UI looks more like this:

Even so, the review of our first plugin submission took about a week, and that may have been faster than normal as a result of our direct line of contact with Anthropic solution architects and account executives (to stress again how valuable that relationship has been). We were given a rough estimate of nine days for average review time.

We couldn’t see it then, but we later learned that part of the holdup was that our submission raised a number of warnings to the Anthropic review team:

Policy warnings from the automated review

In retrospect, the extra visibility is nice; but, at the time, I might have ended up making a bunch of unnecessary changes. The Anthropic team ultimately waived all of these warnings. The takeaway here is to wait for a call to action from the reviewer, rather than jumping straight into trying to resolve every policy warning, even if they sound serious.

Warning

What triggered it

Resolution

Uses a credential from the user’s machine

Example curl commands with credentials templated as environment variables.

Waived after manual review. False positive.

No icon

The icon field was undocumented at submission time, and claude plugin validate --strict passed without it.

Waived. The field is now documented.

Contains a download-and-run command

Skill directives instructing an agent to call an API and interpret the response.

Waived after manual review.

Warning: Uses a credential from the user’s machine

The credential warnings pointed at skills that included example curl commands, where the credentials were templated with environment variable syntax. The Elastic CLI was specially designed to ensure that credentials were never exposed to an agentic caller, so we were initially quite alarmed by this report and relieved to discover that these were false positives.

Warning: No icon

The icon warning surprised us, too. At the time, there was no documentation for an icon field being an option as part of the manifest, and our CI had run claude plugin validate --strict ., so we knew that the manifest was valid without that field.

Today, the Plugin manifest: Fields reference does document icon. We take this as a sign that Anthropic is clearly iterating on the plugin experience. New fields show up, but Anthropic doesn’t retroactively block submissions made without them. 

Warning: Contains a download-and-run command

The download-and-run warning also sounded concerning at first, but on closer inspection, it seems to be taking issue with our skills having directives like the following, where API calls are suggested, as is instruction on interpreting the response:

**Verify Kibana connectivity.** Call `GET kbn:/api/status`. If the call fails, stop and surface the error — do not guess endpoints or credentials. Read `version.number` to confirm the cluster meets the 9.4+ requirement.

Surprise: Your Claude plugin is live

When Anthropic concluded its review, the plugin was immediately visible. This didn’t require an extra confirmation step from us, and there was no staging area. We also received no notification that it was live. This truly surprised us. Our plugin was published late on a Thursday, but I didn’t check on it on Friday. Only on the following Monday did we realize that it was live and visible. In our case, no harm done (the skills had been public for months already), but for anyone who’s not shipping something battle-hardened, be sure to do your testing before submitting. 

Where your Claude plugin actually appears

Publishing doesn’t get you into every Claude directory. There are at least four places where a developer might look for plugins:

Directory

Visible on publish?

How to get in

Claude app’s Setting > Plugins > Discover UI

Yes

Submit your plugin at https://claude.ai/directory/manage.

Claude Marketplace (https://claude.com/plugins, https://claude.com/marketplace)

No

Verification process done separately by Anthropic, after publishing.

anthropics/claude-plugins-community repo

No

Curation process done separately by Anthropic, after publishing.

anthropics/claude-plugins-official repo

No

Partner plugins can be listed through Anthropic contact.

When it’s initially published, your plugin only appears in the Anthropic directory in an unverified state, labeled as “Community.” And this is only if your license or account isn’t configured to exclude unverified plugins. This caused some initial confusion internally (our IT department has Claude Enterprise set up to hide “Community” plugins); we could only see our own plugin when we weren’t logged in with our work accounts.

To get into the other directories and marketplaces, the plugin needs to go through a separate “verification” or “marking” process. Once again, DMs with Anthropic partners proved very helpful:

What’s next for the Elastic Claude plugin

We're still working on getting the plugin verified for the web marketplace and on getting it installed for Elastic's own Claude org so our engineers can dogfood it. The plugin is young, and there are a lot of features we’d like to add. 

But if there's one thing I'd want you to take from this post, it's that the hardest parts of this process weren't technical. They were the gaps between what was expected and what actually happened, and every one of those gaps got closed by a conversation with a real person. The tools are getting smarter, but the communities around them still run on people helping people.

If you're working through publishing your own plugin and get stuck, reach out on our Elastic Stack Community Slack or find me on LinkedIn. And consider sharing what you’ve learned, too. See you in the marketplace.

You've got your issue-tracking, your note-taking, your meeting transcripts, your wiki pages, your video recordings, your chats and IMs and DMs. And don't forget the emails!

It's no wonder that so many enterprises are trying to create workplace search experiences - giving their employees a centralized, one-stop-shop for searching for internal information.

With Elastic's catalog of connectors, this is relatively easy to do. But after you get all your data indexed and ready to be searched, how do you ensure that it is secured? After all, Tess (from Engineering) shouldn't be looking at Bob's (from HR) notes on performance reviews. How can you make sure that each separate user who comes to this unified search bar does gets their own unique view into only the data that they're authorized to view?

Enter, Document Level Security (DLS).

Understanding document level security (DLS) in Elasticsearch

Folks who've followed Elasticsearch for a while may already be aware that DLS has been an Elasticsearch feature for quite a long time. It's part of the larger theme of user authorization, and is really quite simple. You embed metadata in Elasticsearch documents, and then you craft an Elasticsearch query, filtering based on that document metadata, that describes the user's authorization. That query is used to create an Elasticsearch Role.

At query time, when the search user authenticates, their role(s) (if any) is identified, and the embedded query filter (if any) is applied to their searches.

Let's look at a simplistic example. Say we have two documents:

A query that would fetch only my data would be:

That query can be embedded into a Role, like:

So if my user is assigned the role my_role, if I just do

I will only see document 1, but not document 2.

While this example is simple in theory, it has a relatively large number of moving pieces.

• you must ensure that the documents contain the relevant metadata ("my-data": true vs "my-data": false)

• you must trust that the metadata on those documents is accurate

• you must create a Role for every search user with a finely crafted Elasticsearch query

• you must ensure that every role you create correctly maps to the right user at query time

• you mush ensure that all of the above stays up to date.

That last one is particularly difficult. When people in your enterprise join, leave, switch teams, or get promoted, that requires changes - potentially to both your (meta)data AND your Roles. And if you add in data sources that support sharing or access editing, you're definitely needing to make sure that your (meta)data stays up-to-date.

DLS with Elastic connectors

Connector document level security builds off of the Elasticsearch DLS primitives. For many connectors, this includes syncing the relevant metadata and Role Descriptors to support DLS. This results in the documents in your content index automatically containing metadata (usually in a _allow_access_control field) to describe the people/groups who are authorized to search for this document, as well as documents in a special .search-acl-filter-<index-name> index that contain the Role Descriptor JSON necessary to build a concrete Role or an API key for a given search user.

You can find which connectors have DLS available here. For this blog, we're going to reference an example application which utilizes the Sharepoint Online connector. This was the first connector we enabled DLS on, but the example could be easily adapted to work with any DLS-enabled connector.

If your connector is eligible, and you have a Platinum+ Elasticsearch license, you can enable DLS through a toggle on the connector configuration page.

From there, it's just a matter of running a Full sync and an Access Control sync, and Elasticsearch will have all the data it needs.

DLS implementation example

And then what?

Once Elasticsearch has Role Descriptors and document data with sufficient metadata for those role filters, you're ready to build a secure search experience.

We've built an example knowledge search app that we'll use for this blog, and you're welcome to go take a look at its source code. However, we do want to stress that this is an example only - it is not ready to be run in production on its own. Please exercise good judgement and do not run code that you have not read or do not understand.

This application has a pretty simple architecture.

It is composed of a Flask backend and a React frontend. The backend is configured with environment variables to establish a connection with Elasticsearch.

Using this connection, the backend provides three endpoints:

1. GET /api/persona This endpoint lists the identifiers for the "identities" or "personas" that the connector found during the Access Control sync. The frontend uses this list to populate a dropdown of personas so to demonstrate how search results change depending on the selected persona.

2. GET /api/indices This endpoint lists which indices have been included in your Search Application. The frontend uses this list to allow you to choose which ones to search against.

3. GET /api/api_key?persona=<persona> This endpoint creates and returns an Elasticsearch API key based off of a selected persona. In a production system, persona wouldn't be a request argument, but would be inferred from the authentication credentials. This API key is then used by the frontend to issue search requests to Elasticsearch.

Caveats

As stated above, this example should not be used in production. Gaps include:

• It does not implement authentication. A production-ready app would need a way for users to authenticate, and have their identities verified, rather than selecting a user from a dropdown.

• It does not utilze SSL/TLS. The backend currently transmits Elasticsearch API Keys to the frontend over HTTP, not HTTPS.

• The frontend issues /_search requests directly to Elasticsearch. Depending on the production use case, you may not want to expose Elasticsearch to your end user like this. Instead, it may be advisable to issue requests from the frontend to your backend (again, with authentication implemented), and have the backend translate those requests to Elasticsearch queries.

Source Code

Below we link to the critical pieces of code that are necessary to implement search with DLS.

Creating the authenticated user's role descriptor

Code link

You may notice that the query template in this role descriptor is significantly more complex than the simple example provided earlier in this blog. This query does several things:

1. It uses a query template, instead of an explicit query. This makes it easier when reading to separate a long list of permissions from the query syntax.

2. It uses a bool query. This allows us to combine several logical checks.

3. It grants access to any documents that do not contain the _allow_access_control field

4. It grants access to documents where the _allow_access_control field contains a value found in this user's permissions

Creating an API Key from that Role Descriptor

Code link

Searching with the API Key

Code link