Navin library: skills, plugins, MCP, channels and rules per project

Version française : ../../fr/guides/navin-library.md

What the library holds

The platform ships the library of the Navin package in catalog/navin: 276 skills, 17 plugins, 28 commands, 14 agents, 31 MCP server presets, 10 messaging channels (Discord, email, Matrix, Mattermost, Microsoft Teams, Signal, Slack, Telegram, WebSocket, WhatsApp) and 6 project rule sources. catalog/navin/index.json gives the sha256 digest of every item. The copy is updated with python tools/navin_library/sync.py; python tools/navin_library/sync.py --check reports a copy that no longer matches the source.

GET /v1/navin-library gives the version and the counts, GET /v1/navin-library/{kind} lists one kind (skills, plugins, commands, agents, mcp-presets, channels) and GET /v1/navin-library/{kind}/{name} gives the content of one item.

Publishing to Harbor

Every skill, plugin, command and agent of catalog/navin is also published to the Harbor of the Navin Trusted Hub, in the projects skills, plugins, commands and agents: one OCI bundle per item, registry.navinspire.ai/<project>/<name>:<version of the Navin package>, whose single layer is the reproducible tar of the item, with its licence (annotation org.opencontainers.image.licenses). The Hub catalogue declares the same repositories in hub/catalog/library.yaml, generated by python hub/tools/generate_library.py (checked in CI with --check).

1. python tools/navin_library/library_hub_release.py plan builds the bundles in dist/navin-library/<version> and writes the plan release/navin-library/hub-release.json (sha256 digest of every bundle).
2. python tools/navin_library/library_hub_release.py check --strict checks that the plan matches the library and that the Hub knows every item with its licence.
3. python tools/navin_library/library_hub_release.py publish, with HUB_API, HUB_TOKEN, REGISTRY_USER and REGISTRY_PASSWORD in the environment, pushes every bundle to the staging project, checks its digest, then registers it in quarantine with hub/pipeline/publish.sh --register-only. A rerun skips the items already registered. The releases stay in quarantine until the publication gate of the Hub promotes them.
4. python tools/navin_library/library_hub_release.py verify --location quarantine (or published) pulls every bundle back and compares its bytes with the plan.

A Harbor tag is immutable: an item already registered that changes needs a new version of the Navin package.

Activate in a project

Everything happens per project of the tenant: another project sees neither its activations, nor its MCP servers, nor its channels, nor its rules. POST /v1/projects/{project_id}/navin-library/activations activates a skill, a plugin, a command or an agent. An activated skill is registered in the skill registry with the library signature and the Skill Loader serves it like any signed skill. A plugin activates its skills, commands and agents, and removes them with it (DELETE /v1/projects/{project_id}/navin-library/activations/{activation_id}).

from enterprise_ai import EnterpriseAI

client = EnterpriseAI("<control-plane-url>", api_key="eai_...")
client.navin_library.activate("alpha", "plugin", "hookify")
print(client.navin_library.project("alpha")["counts"])

MCP servers from a preset

POST /v1/projects/{project_id}/navin-library/mcp-presets/{name}/install creates an MCP server of the project. Secret fields are only given as openbao:// or env:// references. An HTTP preset goes through the MCP gateway; a stdio preset (a local command such as npx or uvx) is started from the MCP page of the Navin Manager, per tenant and project, which tests the connection and seals the secrets, then is registered here by the URL of its HTTP endpoint.

client.navin_library.install_mcp_preset("alpha", "browserbase", url="https://mcp.browserbase.com/mcp",
                                        credential_refs={"browserbase_api_key": "openbao://mcp/browserbase"})
client.mcp.list_servers(project="alpha")

Reusable channels

POST /v1/projects/{project_id}/navin-library/channels/{name}/install creates a channel of the project from the contract of a Navin channel: every field is checked (kind, choices, required fields) and secrets stay references. The channel bridge of the Python SDK relays the messages of the Navin adapter to POST /v1/channels/{name}/inbound and sends the answer of the agent back.

import asyncio

from enterprise_ai.channels.bridge import ChannelBridge
from enterprise_ai.runtime.bus import BusMessage, MessageBus

client.navin_library.install_channel("alpha", "telegram", settings={"allowFrom": ["42"]},
                                     secret_refs={"token": "env://TELEGRAM_TOKEN"}, agent_ref="agent:support")
bridge = ChannelBridge(client, "telegram-alpha")
bus = MessageBus()
asyncio.run(bridge.handle(BusMessage(content="Hello", session_id="chat-1", sender="42"), bus))

With the Navin package installed, bridge.load_adapter(bus) instantiates the Navin adapter of the channel (Telegram, Discord, Slack...) on the same bus and bridge.run(bus) relays every message.

Project rules

POST /v1/projects/{project_id}/rules/import reads the rule files of a repository: .navin/rules/*.md, .cursor/rules/*.mdc (alwaysApply, description, globs), .cursorrules, .clinerules, .windsurfrules and .github/copilot-instructions.md. PUT /v1/projects/{project_id}/rules/{name} writes a rule, GET /v1/projects/{project_id}/rules/prompt gives the prompt section every run of the project receives: always on rules inlined, conditional rules listed with their globs.

client.navin_library.import_rules("alpha", "./my-repo")
print(client.navin_library.rules_prompt("alpha")["prompt"])

Procedures

The screen is Developer Studio > Navin library (portal/src/screens/navin-library.tsx), with the tabs Catalogue, Active in the project, MCP, MCP instances, Channels and Rules. Activating and installing need the tenant administrator, developer or application owner role; other roles see the library read only.

1. Choose the project. Every activation, MCP server, channel and rule belongs to one project, so nothing leaks to another project of the tenant.

   Screen: Navin library, field Project.

   Expected result: the counts of the library and of the project show.

   If it fails: "No project yet" means the tenant has no project; create one in Administration > Projects and environments. 404 project_not_found means an unknown project for your tenant.

2. Activate a skill, a plugin, a command or an agent. Activation registers the item for the project; an activated skill is served by the Skill Loader like any signed skill.

   Screen: Catalogue, choose the type, open the item, Activate in the project. API: POST /v1/projects/{project_id}/navin-library/activations.

   Expected result: "Activated: n item(s)"; the item is listed in Active in the project, a plugin with what it brought.

   If it fails: 422 navin_library_kind_not_activable means a type that is installed, not activated (MCP presets and channels); 409 navin_skill_name_taken means a skill of the same name, not from the library, already exists; 404 navin_library_item_not_found means an unknown item.

3. Install an MCP server from a preset. The form only accepts references for secret fields, so no secret is stored by the platform.

   Screen: MCP, choose the preset, Install, fill the fields (secret fields as openbao:// or env:// references), Install. API: POST /v1/projects/{project_id}/navin-library/mcp-presets/{name}/install.

   Expected result: "MCP server installed"; the server is listed under the MCP servers of the project.

   If it fails: 409 mcp_preset_needs_endpoint means a stdio preset without the HTTP endpoint that exposes it; 422 mcp_preset_secret_ref_required means a secret given as a value; 422 mcp_preset_field_missing lists the missing fields; 409 mcp_preset_not_installable means a preset that cannot be installed.

4. Install a channel. The form is generated from the setup contract of the Navin channel.

   Screen: Channels, choose the channel, fill the form, install. API: POST /v1/projects/{project_id}/navin-library/channels/{name}/install.

   Expected result: "Channel installed"; the channel is listed in the channels of the project.

   If it fails: 422 channel_field_invalid (wrong type or choice), 422 channel_field_missing (a requirement not met), 422 channel_secret_ref_required (a secret given as a value).

5. Import or write the project rules. Rules are the instructions every run of the project receives.

   Screen: Rules, Import from a repository (files or folder, paths relative to the repository root), then Import; or New rule, then Save the rule. Prompt preview shows the section the runs receive.

   Expected result: "Imported: n rule(s)", with the skipped files and their reason (not a rule file, empty, too large).

   If it fails: 422 rule_empty, 413 rule_too_large, 422 rule_name_invalid, 422 rule_scope_required (a conditional rule with neither globs nor description).

6. Remove an activation. Removing a plugin removes the skills, commands and agents it brought.

   Screen: Active in the project, Remove, then Confirm. API: DELETE /v1/projects/{project_id}/navin-library/activations/{activation_id}.

   Expected result: "Removed: n item(s)".

   If it fails: 404 navin_library_activation_not_found.

Troubleshooting

Status	Code	Cause	Fix
503	navin_library_unavailable	the vendored library cannot be read	run python tools/navin_library/sync.py --check and restore catalog/navin
404	navin_library_kind_unknown	type outside skills, plugins, commands, agents, mcp-presets, channels	use one of the listed types
404	project_not_found	project unknown in your tenant	check the project identifier
409	navin_skill_name_taken	a skill of that name, not from the library, already exists	remove or rename the existing skill
409	mcp_preset_needs_endpoint	stdio preset without HTTP endpoint	start it from the MCP page of the Navin Manager, then give its URL
422	mcp_preset_secret_ref_required	secret given as a value	give an openbao:// or env:// reference
422	channel_field_missing	channel requirement not met	fill one alternative of each requirement
404	rule_not_found	unknown rule name	list the rules with GET /v1/projects/{project_id}/rules

Next steps

• MCP Development Guide
• Skill Development Guide
• Plugin Development Guide
• Architecture decision: docs/architecture/ADRs/en/ADR-0164-navin-library-per-project.md