Atomemo-official-plugins atomemo-plugin-development

install

source · Clone the upstream repo

git clone https://github.com/choice-open/atomemo-official-plugins

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/choice-open/atomemo-official-plugins "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.agents/skills/atomemo-plugin-development" ~/.claude/skills/choice-open-atomemo-official-plugins-atomemo-plugin-development && rm -rf "$T"

manifest: .agents/skills/atomemo-plugin-development/SKILL.md

source content

Atomemo Plugin Development

You are helping a developer build an Atomemo plugin. Atomemo plugins extend the platform with:

Tools: External API wrappers or local functions
Models: LLM definitions with capabilities, pricing, and parameter overrides
Credentials: Secure authentication definitions used by tools and models

Architecture Overview

Host (Atomemo App)
      ↕
  Plugin Hub          ← secure intermediary for lifecycle + message routing
      ↕
  Your Plugin         ← SDK + your business logic

Plugin Hub decouples the host and plugin and handles communication security
SDK (
```
@choiceopen/atomemo-plugin-sdk-js
```
) provides
```
createPlugin
```
, runtime context, file helpers, schemas, and type-safe plugin definitions
CLI (
```
@choiceopen/atomemo-plugin-cli
```
) scaffolds projects and manages auth plus debug setup

Read

references/core-concepts.md

first when the developer needs architectural context.

Main Component Types

Type	Purpose	Source directory
Tool	Invokes third-party services or local business logic	`src/tools/`
Model	Declares an LLM and its capabilities	`src/models/`
Credential	Collects and transforms authentication data	`src/credentials/`

A single plugin can contain multiple tools, models, and credentials.

Identify the Scenario

Scenario A — New project from scratch: Read:

```
references/quick-start.md
```
```
references/core-concepts.md
```
The relevant implementation guides below

Scenario B — Adding to an existing project: Read the relevant guide directly:

Adding a Tool →
```
references/tool-plugin.md
```
Adding a Model →
```
references/model-plugin.md
```
Adding Credentials →
```
references/credential.md
```
Configuring Parameters →
```
references/declarative-parameters.md
```
, then load the specific sub-page(s) it points to for the task at hand
Understanding
```
context.files
```
→
```
references/tool-plugin.md
```

Scenario C — Publishing: Read

references/publishing.md

Workflow

Step 1: Clarify intent

Determine:

Is this a new plugin or an existing plugin?
Does it need tools, models, credentials, or some combination?
Does it need file input/output (
```
file_ref
```
) handling?
Does it need advanced declarative parameters such as
```
resource_locator
```
or
```
resource_mapper
```
?
Is TypeScript acceptable? It is the recommended and best-supported path.

Step 2: Verify the Atomemo CLI

Before running

atomemo

commands, check whether the CLI is installed:

atomemo --version

If missing, install it:

npm install @choiceopen/atomemo-plugin-cli --global

If you need to compare against the latest published CLI:

atomemo --version
npm view @choiceopen/atomemo-plugin-cli version

Only upgrade after confirming with the user:

npm install @choiceopen/atomemo-plugin-cli@latest --global

Checking versions is safe to automate. Installing or upgrading is not.

Step 3: Set up the project (new projects only)

See

references/quick-start.md

. The normal sequence is:

atomemo auth login
atomemo plugin init
cd <plugin-name>
atomemo plugin refresh-key
bun install

Then in two separate terminals:

# Terminal 1 — watch mode (rebuilds on save, does NOT connect to Hub)
bun run dev

# Terminal 2 — connects to Plugin Hub
bun run ./dist

Step 4: Implement plugin components

Create definitions in the appropriate directories and register them in

src/index.ts

Typical project layout:

src/
  index.ts
  tools/
  models/
  credentials/
  i18n/

Registration pattern:

import { createPlugin } from "@choiceopen/atomemo-plugin-sdk-js"
import { myTool } from "./tools/my-tool"
import { myModel } from "./models/my-model"
import { myCredential } from "./credentials/my-credential"

const plugin = await createPlugin({ /* manifest fields */ })
plugin.addTool(myTool)
plugin.addModel(myModel)
plugin.addCredential(myCredential)
plugin.run()

For

createPlugin(...)

metadata, do not invent a brand-new manifest shape from memory. Open the existing

src/index.ts

first and preserve the scaffolded structure unless the developer explicitly wants to change plugin metadata. Keep the metadata used by

createPlugin(...)

aligned with

package.json

and README details; see

references/core-concepts.md

for entrypoint guidance and

references/publishing.md

for the metadata consistency requirement.

Step 5: Declarative parameters and file handling

Use declarative parameters for user input and configuration. Start with:

```
references/declarative-parameters.md
```
— index only; read this to find the right sub-page, then load the specific sub-file(s) you need

references/declarative-parameters-overview-and-core-concepts.md

— load this alongside the index for foundational knowledge

references/declarative-parameters-examples.md

Then load the focused page that matches the question:

Need allowed

type

values or plugin-type support →

references/declarative-parameters-property-type-overview.md

Need common schema keys such as

required

display

ui

depends_on

, or

decoder

→

references/declarative-parameters-property-base.md

Need the full definition of a scalar, object, array, or special property type → the matching basic/composite/special type page

Need UI component names or default rendering behavior →

references/declarative-parameters-property-ui-reference.md

and

references/declarative-parameters-default-ui-behavior.md

Need dynamic visibility rules →

references/declarative-parameters-display-condition.md

Need Tool-only remote selection or mapping flows →

references/declarative-parameters-resource-locator.md

and

references/declarative-parameters-resource-mapper.md

Need examples to adapt quickly →

references/declarative-parameters-examples.md

When a tool handles files, use

context.files

helpers instead of manually treating file references as plain JSON.

Step 6: Internationalization

All user-facing strings support i18n. Prefer the

t()

helper:

import { t } from "../i18n/i18n-node"

display_name: t("WEATHER_TOOL_DISPLAY_NAME"),
description: t("WEATHER_TOOL_DESCRIPTION"),

Step 7: Test locally

bun run build
bun run ./dist

bun run dev

rebuilds in watch mode but does not connect to Plugin Hub — run it in a separate terminal from

bun run ./dist

, which creates the actual Hub connection.

Step 8: Publish (when ready)

See

references/publishing.md

. Key steps:

```
bun run release
```
— validates, builds, syncs versions
Fork
```
atomemo-official-plugins
```
repo
Add plugin to
```
plugins/<your-plugin-name>/
```
Open PR with title
```
feat(plugin): add <your-plugin-name>
```

Reference Files

Load these on demand based on what the developer needs:

File	When to read
`references/quick-start.md`	New project setup
`references/core-concepts.md`	Architecture, plugin entrypoint, metadata consistency, lifecycle
`references/tool-plugin.md`	Building Tool plugins
`references/model-plugin.md`	Building Model plugins
`references/credential.md`	Defining credentials
`references/declarative-parameters.md`	Parameter routing guide + TOC; use it to choose the correct focused reference page
`references/declarative-parameters-examples.md`	Ready-to-copy parameter examples
`references/publishing.md`	Publishing to the marketplace

CLI Automation

You can automate most CLI steps except the browser-based login flow.

Safe commands to run automatically:

atomemo --version
npm view @choiceopen/atomemo-plugin-cli version
atomemo plugin init --no-interactive -n <plugin-name> -d "<description>" -l typescript
atomemo plugin refresh-key
bun install
bun run build
bun run ./dist

Commands that require user action:

atomemo auth login

uses a device authorization flow. You cannot automate it. Guide the user through the browser verification step and wait for confirmation.

Common Mistakes to Avoid

Plugin names must match
```
/^[a-z][a-z0-9_-]{2,62}[a-z0-9]$/
```
Never hardcode secrets
Model names should follow
```
provider/model_name
```
Debug API keys expire; refresh with
```
atomemo plugin refresh-key
```
Tools that handle files should use
```
context.files
```
Every tool, model, and credential must be registered in
```
src/index.ts
```