---
name: hana-plugin-creator
description: Create Hana plugin scaffolds and guide users through beginner or developer plugin planning, capability checks, manifest setup, runtime tools, iframe UI, SDK templates, and install-ready plugin directories. Use when Hanako/Codex needs to explain what Hana plugins can do, help a user describe a plugin idea, check whether the SDK supports it, or generate/update a Hana plugin with @hana/plugin-runtime, @hana/plugin-sdk, and @hana/plugin-components.
metadata:
  default-enabled: false
---

# Hana Plugin Creator

Use this skill for Hana application plugins, not Codex `.codex-plugin` bundles.

## First Contact

On first use, give a map, not an encyclopedia. Explain what Hana plugins can add, ask what the user wants to build, and invite follow-up questions. Expand details only after the user asks or after the chosen scaffold needs them.

Choose the user mode this way:

- If the user explicitly says they are new, non-technical, or wants hand-holding, use beginner mode.
- If the user explicitly asks for SDK/API/build details or gives code-level requirements, use developer mode.
- If memory is unavailable, disabled, or uncertain, ask: `你想我用哪种方式帮你创建插件？A. 边讲边做 B. 开发者模式`

Beginner mode tone: encouraging, concrete, and guided. Say that the user can describe the feature in plain language, Hanako will help turn it into a plugin plan and scaffold, and Hanako can answer questions at any step. Ask:

1. 你希望 Hanako 多一个什么能力？
2. 这个能力是让 Agent 自动调用，还是让你点界面使用？
3. 它需要界面、文件、联网、外部平台、账号权限吗？

Developer mode tone: concise and collaborative. Lead with the capability surface, then ask for the target contribution and integration boundary.

After delivering a plugin, encourage with grounded product value. Name the real situation where the plugin helps, such as reducing repeated steps, making an external service available inside Hana, turning a manual workflow into an Agent-callable tool, or giving a recurring task a stable UI. Use natural wording such as `这个想法挺实用，适合把每周重复整理的步骤固定下来` or `这个方向比较适合做成工具型插件，因为 Agent 可以在对话里直接调用`. Avoid inflated praise like `你的设想太棒了`.

## Capability Map

Hana plugins can provide:

- Agent-callable tools and slash-style actions.
- Skills, agents, and knowledge that guide model behavior.
- Iframe pages, widgets, and cards using Hana theme and host capabilities.
- Lifecycle and EventBus handlers for full-access integrations.
- Provider contributions for chat and media capabilities, including image/video/speech providers backed by HTTP, OAuth HTTP, local CLI, browser CLI, or plugin runtimes.
- Extension-style integrations where the app has explicit extension points.
- SessionFile-backed outputs for files and media.

Hana provides install/enable/reload, per-agent skill toggles, manifest capability checks, iframe host messaging, theme tokens, toast/clipboard/external host APIs, EventBus, data directories, and SDK packages.

Current boundaries: iframe UI is the stable extension surface. Native renderer components and code sandboxing are not the default path yet. If a request depends on those, explain the gap and propose the closest supported shape.

## Workflow

1. Find the Hana repo root. Prefer the current workspace if it contains `PLUGIN_SDK.md`, `PLUGINS.md`, and `packages/plugin-runtime`.
2. Read `.docs/PLUGIN-DEVELOPMENT.md`, `PLUGIN_SDK.md`, and relevant sections of `PLUGINS.md` before changing plugin code. For React UI, also read `packages/plugin-sdk/README.md` and `packages/plugin-components/README.md`.
3. Pick a template:
   - `direct`: no npm install, no build step, best for a beginner's first runnable plugin.
   - `guided-react`: React/Vite/SDK starter with shared Hana components and a gentler README.
   - `professional-react`: React/Vite/SDK starter for developers who expect package scripts and typed UI code.
4. Pick the contribution kind:
   - `tool`: restricted plugin with `tools/*.js`.
   - `ui`: full-access iframe page/widget.
   - `full`: tool, lifecycle/EventBus entry, and iframe UI.
   - `provider`: full-access provider declaration under `providers/*.js`.
5. Pick the target location:
   - Built-in plugin shipped with Hana: `plugins/<plugin-id>`.
   - Example or template plugin: `examples/plugins/<plugin-id>`.
   - User-installed plugin: the directory reported by `/api/plugins/settings` or `${HANA_HOME}/plugins`.
6. Generate the scaffold with the bundled script, then adjust names, descriptions, tools, routes, capabilities, and UI to the user's request.
7. Use the Plugin Dev Loop when available:
   - confirm the user has enabled Settings -> Plugins -> "Allow Agent plugin dev tools";
   - install source with `plugin.dev.install`;
   - reload with `plugin.dev.reload` after edits;
   - keep the returned `devRunId` and pass it to lifecycle controls when available;
   - enable, disable, reset, or uninstall only through `plugin.dev.enable`, `plugin.dev.disable`, `plugin.dev.reset`, and `plugin.dev.uninstall`;
   - inspect `plugin.dev.diagnostics`;
   - smoke-test tools with `plugin.dev.invokeTool`;
   - list UI surfaces with `plugin.dev.listSurfaces`;
   - run `manifest.dev.scenarios` with `plugin.dev.runScenario`.
8. For UI debugging, prefer element-first inspection: read accessible elements, role, label, text, and stable locators before screenshots. Use screenshots for visual polish, clipping, theme fit, or fallback.
9. If the user wants publication, choose one channel:
   - local debug: keep source local and install through the dev loop;
   - human review bundle: create zip, README, manifest, screenshots, and sha256 for email/group/issue review;
   - official OH-Plugins release: prepare catalog entry and release zip, then run privacy-push before any remote push.
10. Run focused verification. When editing this skill, at minimum validate the skill and run the scaffold script against a temp directory.

## Scaffold Commands

Beginner starter:

```bash
python3 skills2set/hana-plugin-creator/scripts/create_hana_plugin.py "My Plugin" --path examples/plugins --audience beginner --template direct
```

Developer React starter:

```bash
python3 skills2set/hana-plugin-creator/scripts/create_hana_plugin.py "My Plugin" --path examples/plugins --audience developer --template professional-react --sdk-mode workspace
```

Useful options:

- `--kind tool`: restricted plugin with a static `tools/create-note.js`.
- `--kind ui`: full-access plugin with `page` and `widget` iframe UI.
- `--kind full`: tool, lifecycle/EventBus entry, and iframe UI.
- `--kind provider`: full-access provider contribution with a media-capability provider declaration.
- `--sdk-mode workspace`: use repo-local SDK packages.
- `--sdk-mode bundled`: copy SDK tarballs from this skill into the generated plugin.
- `--dev-scenario`: add a first-phase `manifest.dev.scenarios` smoke test.
- `--force`: replace an existing generated directory only when the user explicitly wants overwrite.

Provider contribution starter:

```bash
python3 skills2set/hana-plugin-creator/scripts/create_hana_plugin.py "Jimeng Provider" --path examples/plugins --kind provider --audience developer
```

## SDK Rules

- Static `tools/*.js` must export `name`, `description`, `parameters`, and `execute`.
- React templates may use `@hana/plugin-runtime`, `@hana/plugin-sdk`, and `@hana/plugin-components`.
- Dev authority is not a manifest permission. Hana grants it from the remembered dev install slot under `${HANA_HOME}/plugins-dev/`, and Agent dev tools are hidden until the user enables the dev tools setting.
- Local files returned to users must go through `toolCtx.stageFile({ sessionPath, filePath, label })`, then media details. Do not hand-build local `MEDIA:` or `file://` output.
- Page and widget contributions require `"trust": "full-access"` and route-backed iframe UI.
- Declare only the iframe host capabilities actually used.
- EventBus handlers should return `HANA_BUS_SKIP` for payloads that do not belong to them.
- Keep iframe UI self-contained. Do not import renderer internals from `desktop/src/react`.
- Provider declarations live in `providers/*.js` and require `"trust": "full-access"`.
- Keep `capabilities.chat` separate from `capabilities.media.*`. Media-only providers must set `chat.projection = "none"` so they never appear in chat model selectors.
- CLI-backed providers must declare `runtime.kind = "local-cli"` or `"browser-cli"` with structured arg bindings and output contracts. Do not build shell command strings.

## Marketplace Rules

- Marketplace metadata lives in the `OH-Plugins` repository, not inside `project-hana`.
- Official source plugins may live in `OH-Plugins/official-plugins/<plugin-id>/` with a matching `plugins/<plugin-id>.yaml`.
- Each marketplace entry needs one README source: `readme`, `readmePath`, or `readmeUrl`. Use `readmePath` only for local file marketplaces; use inline `readme` or HTTPS `readmeUrl` for URL marketplaces.
- Prefer `versions[]` once a plugin has more than one release line. Each version item declares `version`, `compatibility.minAppVersion`, and its own `distribution`.
- For a single release, root `version`, `compatibility`, and `distribution` remain valid; Hana normalizes them into a single version entry.
- Hana selects the highest SemVer version compatible with the current app and exposes update, reinstall, incompatible, and downgrade states to the UI.
- If the selected compatible version is lower than the installed version, install requires explicit downgrade confirmation with `allowDowngrade: true`.
- Release installs are backed up before replacement and rolled back when the new plugin fails to load.
- Local file marketplaces can install `distribution.kind = "source"` entries because paths resolve on disk.
- URL marketplaces browse entries, show README content, and install release packages by downloading the zip and verifying `sha256`.
- Before pushing `OH-Plugins`, run privacy-push and wait for explicit user confirmation.

## UI Rules

- Default React plugin UI to `HanaThemeProvider mode="inherit"` so it follows the host theme.
- Use `mode="hana"` for a named Hana theme, and `mode="custom"` only for explicit token overrides.
- Route shells should read `hana-theme` and `hana-css` query params, include the theme CSS link when present, and escape values inserted into HTML attributes.
- Direct templates may use small no-build host messaging helpers, but should stay compatible with the public iframe protocol.