Terminal
Terminal/Skill
Scaffolds a new Capacitor plugin with iOS and Android native code and a TypeScript API from a plan or YAML contract.
By Ionic
Works with
npx skills add ionic-team/capacitor-skills --skill capacitor-plugin-generatorGenerate a reviewable Capacitor plugin candidate from either human intent or a structured YAML contract. The output should follow the official Capacitor plugin architecture, but it is a first pass that requires human review before release.
✅ Use this skill when:
cordova-capacitor-plugin-migration skill.❌ Do NOT use this skill for:
cordova-capacitor-plugin-migration
first; that skill produces the input contract this skill consumes).| Requirement | Use |
|---|---|
| Node.js LTS and npm | Run the Capacitor plugin generator and package scripts. |
| Xcode | Build and verify iOS output when iOS is targeted. |
| Android Studio and Android SDK | Build and verify Android output when Android is targeted. |
| CocoaPods and Gradle | Resolve native dependencies when required by generated code. |
| Capacitor plugin knowledge | Review generated native bridge code before publishing. |
references/input-contract.md, skip elicitation,
and halt if the optional migration block contains blockers or tier 3 hooks.@capacitor/core,
@capacitor/android, and @capacitor/ios packages. Do not invent helper
classes, utilities, or import paths. When uncertain whether an API exists,
read the package source rather than infer from its name.checkPermissions() /
requestPermissions() flow and document the manual setup.npm publish --access public --dry-run only.Read references/input-contract.md. If the input is YAML with plugin,
platforms, and api, parse it as structured mode and skip questions. If the
input is conversational, elicit the minimum missing fields needed to create the
same contract shape internally.
Read references/scaffolding.md. Run the official Capacitor plugin generator
with non-interactive flags when possible. Enforce name parity:
registerPlugin() JavaScript name equals iOS jsName equals Android
@CapacitorPlugin(name).
Read references/api-design.md. Define src/definitions.ts before native
implementation. Use options/result interfaces per method, string unions instead
of enums, listener signatures for events, and JSDoc with @since everywhere.
Read references/web-guide.md. Extend WebPlugin, feature-detect browser APIs
before use, throw unavailable() when an API exists but is unavailable in the
current browser, and throw unimplemented() when no web equivalent exists.
Register the web layer through a dynamic import.
Read references/api-design.md. For every method, choose one bridge return
type: value, void, or callback. Use callback return types only for streams or
long-lived watchers. Keep event names identical across TypeScript, web, iOS, and
Android.
Read references/architecture-patterns.md and references/ios-implementation.md. Use the
Bridge pattern by default: a thin Capacitor plugin class delegates to an
implementation class. Use a Facade only for complex plugins with multiple native
subsystems, permission flows, or lifecycle concerns.
Read references/architecture-patterns.md and references/android-implementation.md. Use the
Bridge pattern by default: a thin Plugin class delegates to an implementation
class. Use a Facade only for complex plugins with multiple managers, permission
flows, services, activities, or lifecycle hooks.
Read references/sample-app.md. Create or update a sample app that exercises
the entire public plugin API, including success paths, expected errors,
permissions, configuration, and listeners.
Read references/testing-strategies.md and references/publishing.md.
Generate API docs from JSDoc with npm run docgen; do not hand-write API docs.
Run the relevant verify commands for targeted platforms and record any
environment-limited checks.
Read references/publishing.md. Run the pre-publish checklist and dry run:
npm publish --access public --dry-run. Do not publish the generated plugin
without explicit human review outside this skill.
npm init @capacitor/plugin so the
scaffolder runs non-interactively.unimplemented().@since.npm run fmt before committing and npm run verify before
reporting completion.definitions.ts rather than
guessing from human-friendly names.UNAVAILABLE, PERMISSION_DENIED, INVALID_PARAMETER,
OPERATION_FAILED).references/configuration.md runtime plugin configuration.@capacitor/core, @capacitor/android, and
@capacitor/ios packages.notifyListeners(...) from outside the Plugin subclass —
see references/architecture-patterns.md "Event Dispatch Locality".npm publish --access public --dry-run.| Symptom | Fix |
|---|---|
npm init @capacitor/plugin fails with Refusing to prompt in non-TTY environment | Pass all required flags non-interactively: npm init @capacitor/plugin <folder> -- --name "<npm-name>" --package-id "<reverse-dns>" --class-name "<PascalCase>" --description "<one-line>" --author "<name <email>>" --license "<SPDX>" --repo "<url>" --android-lang "<kotlin|java>". See references/scaffolding.md. |
npm init @capacitor/plugin fails with invalid option: --android-lang undefined: Must be either 'kotlin' or 'java' | The --android-lang flag is required when running non-interactively. Add --android-lang "kotlin" (recommended for new plugins) or --android-lang "java" to the command. |
| Plugin silently fails to load | Make registerPlugin() name match iOS jsName and Android @CapacitorPlugin(name). |
| Event not received in JS | Make the event name string identical across TypeScript, web, iOS, and Android. |
| iOS method not callable from JS | Ensure the method is marked @objc and listed in pluginMethods. |
| Android method not callable from JS | Ensure the method is public and annotated with @PluginMethod(). |
npm run verify:ios fails | Run pod install --repo-update; then rerun the iOS verify command. |
npm run verify:android fails | Sync Gradle and check Android SDK, compile SDK, and dependency versions. |
Android compile error: class X is public, should be declared in a file named X.java | Java requires a public class to live in a file matching its name. When generating multiple Java classes per plugin, place each public class in its own file. Kotlin does not impose this rule. |
Android compile error: notifyListeners(...) has protected access in Plugin | notifyListeners() is protected on Plugin. Call it only from inside a class that extends Plugin. If another class needs to emit events, return the data to the plugin and dispatch there, or expose a public wrapper on the plugin that calls notifyListeners() internally. |
Android compile error: cannot find symbol: class … for a com.getcapacitor.* import | The import does not exist on the installed @capacitor/android surface. Verify imports against the package source before generating; do not infer Capacitor classes from their names. |
Android compile error: <method> in <Subclass> cannot override <method> in Plugin; attempting to assign weaker access privileges; was public | A helper on the Plugin subclass collides with a public method that com.getcapacitor.Plugin already defines (e.g., hasPermission, getPermissionState, notifyListeners). Either rename the helper or match the parent's public visibility. |
TypeScript build error: Cannot find type definition file for '<name>' or Invalid module name in augmentation, module '<name>' cannot be found | The augmented module is not installed. Add it to devDependencies (and to tsconfig.json compilerOptions.types if a triple-slash reference is used). Applies to any module augmentation, not just @capacitor/cli. |
TypeScript build error: Interface 'X' incorrectly extends interface 'Y'. Property 'Z' is optional in type 'X' but required in type 'Y' (or the symmetric error) | Do not redeclare members the built-in lib type already provides. Use the lib type directly, or augment via declare global { interface Y { newMember?: ... } } for genuinely new members only. Use 'name' in target runtime guards for capability checks. |
npm run docgen produces empty output | Add JSDoc to src/definitions.ts; docgen reads the TypeScript contract. |
| Web API absent in target browser | Use unavailable() when the API exists but is missing here; use unimplemented() when no web equivalent exists. |
| Structured YAML is rejected | Validate against references/input-contract.md; ensure required base fields are present and blockers are empty. |
| Generated output looks too broad | Split unrelated capabilities into separate plugins and regenerate with a smaller API surface. |
| Generated native code reimplements logic the official plugin delegates to a native SDK | Inspect the official plugin's .podspec / Package.swift / android/build.gradle for native SDK dependencies. If present, declare the same SDK and write a thin adapter — see references/api-design.md "Native Dependency Detection". |
cordova-capacitor-plugin-migration: Analyze Cordova plugins and produce a
structured migration plan for this generator.references/input-contract.md: Structured YAML contract for generator input.references/scaffolding.md: Generator invocation, name parity, and scaffold verification.references/api-design.md: TypeScript API design, JSDoc, event signatures, and method return types.references/web-guide.md: WebPlugin patterns, dynamic import, feature detection, and errors.references/architecture-patterns.md: Bridge and Facade patterns plus event parity.references/ios-implementation.md: iOS bridge, implementation class, permissions, dependencies, and Podspec.references/android-implementation.md: Android bridge, implementation class, permissions, dependencies, and Gradle.references/configuration.md: Capacitor config keys under plugins.<PluginJSName>.references/testing-strategies.md: Local linking, verify commands, hooks, and review workflow.references/publishing.md: Package fields, docgen, checklist, and dry-run publishing.references/sample-app.md: Sample app requirements that exercise the full API.references/permission-patterns.md: Deep-dive on permission flows — multi-permission DispatchGroup on iOS, location delegate, check-before-use / just-in-time / deferred consumer patterns, opening system settings.references/typescript-implementation.md: Deep-dive on TypeScript layer — singleton plugin pattern, typed error classes, full event listener handle bookkeeping, helper utilities, Jest scaffolding.