Use this skill to add a new desktop uploader plugin that matches the current XerahS plugin architecture.
For a concrete native-API example, see docs/proposals/xip/XIP0048-nextcloud-native-plugin-design.md.
Workflow
- Audit existing support before writing code.
- Search the repo for the service name, old uploader code, prior docs, and compatibility layers.
- Determine whether this should be a new plugin, a replacement for an old uploader, or an extension of an existing plugin.
- Research the service's official API and auth model using primary sources.
- Use references/service-research-template.md.
- Prefer the service's native API over generic compatibility endpoints when the native path materially improves auth, chunking, sharing, explorer actions, capability discovery, or reliability.
- Inspect the nearest existing plugin before writing code.
- Read references/pattern-map.md.
- Pick the closest starting point:
- Simple token/manual config:
Bitly.Plugin - Browser login or OAuth:
Dropbox.Plugin - File storage + explorer:
AmazonS3.PluginorNextcloud.Plugin
- Simple token/manual config:
- Scaffold the plugin with
scripts/new-uploader-plugin.ps1. - Replace scaffold placeholders with service-specific logic.
- Keep secrets in
ISecretStore, not in settings JSON. - Add explorer support only if the destination can browse/list remote files with stable semantics.
- Add or refine the Avalonia config UI when the property-grid experience would be weak.
- For Avalonia control, binding, and styling rules, read ../avalonia-guidelines/SKILL.md.
- For visual redesign of a plugin config view, read ../design-ui-window/SKILL.md and set its
target_view_pathtosrc\desktop\plugins\<Name>.Plugin\Views\ConfigView.axaml. - Treat uploader config UI as Avalonia AXAML work, not a web frontend workflow.
- Build the new plugin project, then build
src/desktop/XerahS.sln.
Scaffold Command
Run:
.ai\skills\create-uploader-plugin\scripts\new-uploader-plugin.ps1 `
-PluginName "MyService" `
-PluginId "myservice" `
-DisplayName "MyService Uploader" `
-AddToSolution
This creates:
src/desktop/plugins/MyService.Plugin/XerahS.MyService.Plugin.csprojplugin.json- config model, provider, uploader
- Avalonia config view + viewmodel
Required Conventions
- Keep the plugin under
src/desktop/plugins/<Name>.Plugin/. - Target
net10.0. - Reuse
src/desktop/plugins/Directory.Build.props. - Use
ShareX.<Name>.Pluginnamespaces andXerahS.<Name>.Pluginassembly/project names. - Exclude Avalonia/runtime-shared dependencies from plugin output with
ExcludeAssets=runtime. - Copy
plugin.jsonto output. - If credentials are needed, store them through
ISecretStore. - If importing legacy plaintext settings, implement
IInstanceSecretMigrator. - Keep upload logic inside the plugin uploader/provider, not in core app code.
Implementation Decisions
Use these rules when filling in the scaffold:
- Use
UploaderProviderBaseunless there is a strong reason not to. - Return a concrete
UploaderorGenericUploaderfromCreateInstance. - Override
CreateConfigView()andCreateConfigViewModel()for non-trivial configuration. - Implement
IUploaderExploreronly when the service supports remote listing/content actions. - Make
ValidateSettingsreflect real minimum runtime requirements. - Keep
plugin.jsonmetadata aligned withProviderId, class namespace, and assembly name. - If the service exposes both generic and native endpoints, document why the chosen path is correct for this plugin.
- If the service has staged login or capability discovery, surface that in the config UI instead of hiding it behind a flat settings form.
- If the service already had legacy plaintext settings, add secret migration rather than silently abandoning stored credentials.
Verification
Run both:
dotnet build src\desktop\plugins\<Name>.Plugin\XerahS.<Name>.Plugin.csproj -m:1
dotnet build src\desktop\XerahS.sln -m:1
Use references/review-checklist.md before finishing.