Hana Plugin Creator

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.