Taught Claude Code to Install, Configure, and Debug SWIRL Enterprise Search Engine

Evaluating enterprise search software has a fixed cost that has nothing to do with the software: stand up a server, read the docs, connect a source, debug the connector, configure an LLM. By the time you see a real answer from your own data, a week is gone.

We built a Claude Code plugin that compresses that to about an hour, and along the way learned something more interesting than the time savings: a plugin skill is an executable runbook, and the best way to write one is to watch where the agent researches and move that knowledge upstream.

What it is

swirl-claude-plugin is free and Apache-2.0. It gives Claude Code eight guided workflows for SWIRL, a federated search + RAG engine:

claude plugin marketplace add swirlai/swirl-claude-plugin
claude plugin install swirl@swirl --scope user

Start a new Claude Code session and you have:

Why "an hour" is honest

SWIRL is federated. It queries SharePoint, OneDrive, Box, databases, and web APIs where they live, re-ranks results with local models, and feeds the best passages to the LLM you configure. Nothing is copied, ingested, or indexed; there is no vector database to build.

That is why the evaluation is fast: the usual multi-day step (moving your data into the search engine) does not exist. Claude installs the stack, connects two or three sources, and you are looking at ranked, cited answers from your own documents.

Skills are runbooks, not code

There is no code in the plugin. Each command is a skill: a markdown file whose frontmatter description routes the request and whose body loads focused operational knowledge into Claude's context. The install skill knows the real Docker quick start for each edition and insists on verifying with a live search before declaring success. The troubleshoot skill embodies a support rule we enforce on ourselves: the user's report is data; find the log line before proposing a fix. The skills also encode what NOT to do: never print API keys, never paste secrets into chat, never restart a stack someone is demoing on.

The development loop that actually improves it

Here is the pattern we now use for every release, with a real example.

During a walkthrough, a user asked Claude to "enable the cross-encoder and use larger embeddings instead of spaCy." Claude did what a capable agent does with missing knowledge: it researched. A dozen commands into settings files and compiled modules, the user steered it: ranking models in SWIRL are configured as AI Providers, in the database, like every other model choice. Once pointed there, Claude flipped the reader role to mxbai-embed-large served by the stack's own Ollama sidecar, verified the cross-encoder was already active in each result's explain output, and confirmed the change took effect with no restart.

That transcript became the next release. The rag skill now states it outright: ranking models are AI Providers; do not hunt through settings or source. The cross-encoder ships on by default, so confirm it rather than configure it. The embedding model is whatever provider holds the reader role. Changes apply at query time.

The general form: watch where your agent researches, then move that knowledge into the skill. Research is the tax an agent pays for what the skill does not say. Every walkthrough transcript is a free curriculum; the diff between "what the agent had to discover" and "what it should have known" is exactly the next version of the skill.

If you are building your own plugin

Three practices that will save you real time:

1. Give the plugin an explicit identity. Ship a .claude-plugin/plugin.json with the plugin's name and version, and keep component definitions (skills, commands) in exactly one place. Ambiguity here surfaces on the user's machine, not yours.
2. Test the exact path a stranger will run, from a clean environment. HOME=$(mktemp -d) claude plugin marketplace add you/your-repo && claude plugin install ..., then verify the user-visible surface: the actual command names in a session, not just "installed." Manifest validators check syntax, not experience.
3. Write the description for routing. The frontmatter description is what decides whether a user's phrasing reaches your skill. When a real user's words missed, we added their words to the description.

The loop closes with MCP

The part we like most: /swirl:mcp has Claude wire SWIRL's MCP server into itself. The same assistant that installed your knowledge layer then queries it, with permissions enforced server-side per user. Your agents get governed access to enterprise data; the data never moves.

Try it

• Plugin: claude plugin marketplace add swirlai/swirl-claude-plugin
• Docs: docs.swirlaiconnect.com/claude-plugin
• One-page PDF: datasheet, no registration
• SWIRL Community is open source; want an Enterprise license to evaluate? Work email in, license out; no human will contact you.

Issues and PRs welcome on the repo.