neko-plugin

Create, debug, review, and validate N.E.K.O plugins end to end.

2.7k|303|Updated Jun 29, 2025
One-click install
npx skills add https://github.com/Project-N-E-K-O/N.E.K.O --skill neko-plugin
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: neko-plugin
Source: https://github.com/Project-N-E-K-O/N.E.K.O/tree/main/.agent/skills/neko-plugin
Command: npx skills add https://github.com/Project-N-E-K-O/N.E.K.O --skill neko-plugin

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Developing plugins for the N.E.K.O platform requires understanding a strict manifest contract, SDK facades, package types, UI surface modes, and CLI tooling; this Skill guides the entire plugin lifecycle so work stays correct and inside the allowed workspace.

Core Features & Use Cases

  • Plugin Creation Workflow: Asks minimum design questions, locks the plugin identity, scaffolds with uv run neko-plugin init, and writes a DESIGN.md brief.
  • Debugging and Validation: Runs neko-plugin check, hosted TSX checks, and targeted plugin tests to diagnose manifest, entry, runtime, and UI failures.
  • Contract-Driven Review: Reviews plugin diffs against boundary, identity, manifest, SDK, UI/permissions, runtime, and validation labels.
  • Use Case: When asked to add a settings panel to an existing plugin, the Skill reads the plugin contract references, edits only inside plugin/plugins/<plugin_id>/, adds a Hosted TSX surface with minimum permissions, and validates it with the focused checks.

Quick Start

Use the neko-plugin skill to create a new N.E.K.O plugin called weather that fetches forecasts and exposes a settings panel.

Frequently Asked Questions about neko-plugin

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I create a new N.E.K.O plugin?

Create a N.E.K.O plugin by answering the minimum design questions, locking the plugin identity, then running `uv run neko-plugin init <plugin_id> --type plugin --name "<Name>"`. Do not hand-create the plugin directory, plugin.toml, or entry class; the CLI scaffold generates them.

How do I debug a N.E.K.O plugin that fails to load?

Run `uv run neko-plugin check <plugin_id|plugin_path>` first to validate the manifest, entry class, and decorators. Then inspect plugin.toml, verify runtime-triggered @plugin_entry handlers are async def, and check logs and lifecycle state before editing inside the plugin workspace.

What is the difference between plugin, extension, and adapter package types?

A plugin is the default independent feature type. An extension adds entries or hooks to an existing host plugin and requires [plugin.host]. An adapter bridges an external protocol or request stream into N.E.K.O plugin calls; calling an external API alone does not make something an adapter.

Which UI mode should I use for a N.E.K.O plugin panel?

Use Hosted TSX for new interactive plugin UI such as settings panels, dashboards, and forms. Use Markdown for read-only guides and docs, and reserve Static HTML only for legacy standalone pages or browser capabilities Hosted TSX cannot support.

Can a N.E.K.O plugin edit files outside its workspace?

No. The default writable area is only plugin/plugins/<plugin_id>/. Docs, tests, examples, and platform source are read-only context; platform edits require explicit user request or a documented escalation describing the smallest out-of-bound change.

Why does my N.E.K.O plugin entry fail when triggered at runtime?

Runtime-triggered @plugin_entry handlers must be declared as async def; sync entries can be discovered but fail when triggered. Also verify input_schema and params are not both set, and return Ok/Err results instead of raising exceptions.