Load Plugin

​

How It Works

​

The One Field That Matters

requests.post(
    f"{base_url}/api/v1/app-conversations",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "plugins": [
            {
                "source": "github:OpenHands/enterprise-cookbook",
                "ref": "main",
                "repo_path": "load-plugin/dad-joke",
            }
        ],
        "initial_message": {
            "role": "user",
            "content": [{"type": "text", "text": "/dad-joke:about duck"}],
        },
    },
)

​

Two Ways to Drive It

1. Run a skill immediately via an entry command. Send the plugin’s slash command as the first message. The SDK registers /dad-joke:about as a keyword trigger, so this tells a joke right away:
   python load_plugin.py --message "/dad-joke:about duck"
   
2. Load the plugin, then prompt normally. Send a natural-language message; the plugin’s skills are available for the agent to use when relevant. The bundled skill fires on “dad joke”, asks for your favorite animal, then delivers:
   python load_plugin.py --message "Tell me a dad joke"
   

​

Run It

pip install requests
export OH_API_KEY="sk-oh-..."     # Cloud API key

python load_plugin.py             # dad-joke + "/dad-joke:about duck"

​

Options

​

Loading a Private Plugin

python load_plugin.py \
    --source 'https://x-access-token:${GIT_TOKEN}@github.com/me/private-plugins.git' \
    --repo-path plugins/my-plugin \
    --message '/my-plugin:start' \
    --secret GIT_TOKEN="$GIT_TOKEN"

• Braced ${VAR} only — a literal $ in a token is never mangled.
• Secrets only, not host env — host environment variables are never folded into the URL (that would be a credential-exfiltration vector).
• Missing secret → left untouched — the placeholder stays verbatim, so you get a clear clone failure rather than a surprising default.
• Stays redacted — the persisted plugin spec keeps the ${VAR} placeholder, not the secret value.
• HTTPS, not ssh:// — the credential travels inside the URL; SSH authenticates out-of-band (a key), so there is no placeholder to expand.

​

The Bundled Plugin

dad-joke/
├── .claude-plugin/
│   └── plugin.json          # manifest: name, entry_command, parameters
├── commands/
│   └── about.md             # the /dad-joke:about slash command
└── skills/
    └── dad-joke/
        └── SKILL.md         # keyword skill: asks your favorite animal first

​

Related