feat: add postiz plugin

README.md

@@ -30,6 +30,7 @@ Each plugin lives in `plugins/<slug>`. The directory name is the install keyword
 | `linear` | Linear SDK scripting skill for issue, project, team, cycle, and comment workflows. |
 | `mac-notify` | macOS notifications when a Cline run completes. |
 | `nanobanana` | Image generation through OpenRouter and Gemini image models. |
+| `postiz` | Postiz social media scheduling skills with safety rules for posting, media upload, and analytics workflows. |
 | `speak` | Speaks completed Cline replies with ElevenLabs text to speech. |
 | `typescript-lsp` | TypeScript language service `goto_definition` support. |
 | `weather-metrics` | Demo weather tool plus runtime metrics hooks. |

plugins/postiz/README.md

@@ -0,0 +1,38 @@
+# postiz
+
+Postiz workflow guidance for Cline. It helps agents plan and execute social media scheduling work through the user's own Postiz CLI or API credentials.
+
+## What It Does
+
+Installs skills for Postiz setup, integration discovery, content scheduling, media upload, platform settings, and analytics triage.
+
+## Install
+
+```bash
+cline plugin install postiz
+```
+
+For local development from this repository:
+
+```bash
+cline plugin install ./plugins/postiz --cwd .
+```
+
+## Example Usage
+
+After installation, ask Cline:
+
+```text
+Help me draft a LinkedIn and X launch post, discover the required Postiz integration IDs, and prepare the commands to schedule it for tomorrow.
+```
+
+## Requirements
+
+- The `postiz` CLI installed by the user when live Postiz operations are needed.
+- A Postiz account with connected social integrations.
+- Authentication through `postiz auth:login` or `POSTIZ_API_KEY`.
+- `POSTIZ_API_URL` only for custom or self-managed Postiz API endpoints.
+
+## Security Notes
+
+The plugin does not install the Postiz CLI, run an auth server, store credentials, or register an MCP server. Cline should ask before live posting, scheduling, deleting, changing status, uploading media, running `postiz auth:login`, or persisting any API key.

plugins/postiz/index.ts

@@ -0,0 +1,10 @@
+import type { AgentPlugin } from "@cline/sdk"
+
+const plugin: AgentPlugin = {
+	name: "postiz",
+	manifest: {
+		capabilities: ["skills"],
+	},
+}
+
+export default plugin

plugins/postiz/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "postiz",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Cline plugin with Postiz social media scheduling skills.",
+  "cline": {
+    "plugins": [
+      {
+        "paths": [
+          "./index.ts"
+        ],
+        "capabilities": [
+          "skills"
+        ]
+      }
+    ]
+  }
+}

plugins/postiz/skills/postiz-cli/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: postiz-cli
+description: Use Postiz from Cline through the user's Postiz CLI for authentication, integration discovery, media upload, post scheduling, post management, and analytics. Use when the user wants to publish, schedule, inspect, or analyze social content across connected Postiz channels.
+---
+
+# Postiz CLI
+
+Use the user's own `postiz` CLI for live work. Do not install it, authenticate it, upload media, schedule content, delete posts, or write credential files unless the user has asked for that action.
+
+## Setup Checks
+
+1. Check whether the CLI exists with `postiz --help` or `command -v postiz`.
+2. Check authentication with `postiz auth:status`.
+3. If auth is missing, offer either `postiz auth:login` for the device flow or `POSTIZ_API_KEY` for API-key use.
+4. Ask before running `postiz auth:login`, because it stores OAuth credentials in the user's home directory.
+5. Ask before persisting credentials to shell profiles or config files.
+
+For custom or self-managed Postiz instances, use `POSTIZ_API_URL`. Do not invent the URL. Ask the user or read it from an existing project config only when that config is relevant to the user's task.
+
+## Safe Workflow
+
+Use this order for most tasks:
+
+1. Discover connected channels with `postiz integrations:list`.
+2. Get platform requirements with `postiz integrations:settings <integration-id>`.
+3. Fetch dynamic platform data with `postiz integrations:trigger <integration-id> <method>` when the settings mention required lookup data.
+4. Upload media with `postiz upload <file>` before using it in a post.
+5. Create a draft first when the user is still reviewing wording, targeting, timing, or media.
+6. Schedule only after the user confirms the final content, platform list, time, and media.
+7. Use analytics commands after publishing to inspect performance or resolve missing release IDs.
+
+## Common Commands
+
+Authentication:
+
+```bash
+postiz auth:status
+postiz auth:login
+postiz auth:logout
+```
+
+Integration discovery:
+
+```bash
+postiz integrations:list
+postiz integrations:groups
+postiz integrations:settings <integration-id>
+postiz integrations:trigger <integration-id> <method-name> -d '{"key":"value"}'
+```
+
+Post creation:
+
+```bash
+postiz posts:create -c "Content" -s "2026-12-31T12:00:00Z" -t draft -i "integration-id"
+postiz posts:create --json post.json
+```
+
+Post management:
+
+```bash
+postiz posts:list
+postiz posts:status <post-id> --status draft
+postiz posts:status <post-id> --status schedule
+postiz posts:delete <post-id>
+```
+
+Analytics:
+
+```bash
+postiz analytics:platform <integration-id> -d 30
+postiz analytics:post <post-id> -d 30
+postiz posts:missing <post-id>
+postiz posts:connect <post-id> --release-id "<content-id>"
+```
+
+## Confirmation Gates
+
+Ask for explicit confirmation before:
+
+- Uploading media to Postiz.
+- Running `postiz auth:login`.
+- Creating scheduled posts.
+- Promoting drafts into scheduled posts.
+- Deleting posts.
+- Connecting missing platform content to a Postiz post.
+- Running broad analytics or exports across many customer groups.
+- Persisting `POSTIZ_API_KEY`, OAuth credentials, or `POSTIZ_API_URL`.
+
+## Media Rule
+
+Do not pass raw local file paths or arbitrary external URLs directly as post media. Upload the file first:
+
+```bash
+UPLOAD_JSON=$(postiz upload ./asset.mp4)
+MEDIA_URL=$(printf '%s' "$UPLOAD_JSON" | jq -r '.path // .url')
+postiz posts:create -c "Launch video" -m "$MEDIA_URL" -s "2026-12-31T12:00:00Z" -i "integration-id"
+```
+
+If `jq` is not available, inspect the upload response and use the returned Postiz media path or URL manually.
+
+## Analytics Missing Release IDs
+
+Some platforms publish successfully but do not immediately return a platform post ID. If `postiz analytics:post <post-id>` reports missing content:
+
+1. Run `postiz posts:missing <post-id>`.
+2. Show the candidate platform content to the user.
+3. Ask which item to connect.
+4. Run `postiz posts:connect <post-id> --release-id "<content-id>"` only after confirmation.
+
+## Error Handling
+
+- Auth failures usually mean the CLI has no valid OAuth credential or `POSTIZ_API_KEY`.
+- Invalid integration IDs should route back to `postiz integrations:list`.
+- Platform settings errors should route back to `postiz integrations:settings <integration-id>`.
+- Media errors should route back to `postiz upload`.
+- Shell quoting errors are common with JSON settings. Prefer JSON files for complex multi-platform posts.

plugins/postiz/skills/postiz-content/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: postiz-content
+description: Plan Postiz social media campaigns across multiple channels, including channel-specific settings, draft-first review, media preparation, scheduling, and analytics follow-up. Use when the user asks for help turning content into Postiz-ready social posts.
+---
+
+# Postiz Content Planning
+
+Use this skill to turn user goals into safe, reviewable Postiz campaigns. Prefer draft-first workflows unless the user explicitly asks to schedule or publish.
+
+## Campaign Planning
+
+Collect or infer:
+
+- Audience and goal.
+- Platforms or connected channels.
+- Time zone and desired schedule.
+- Required media assets.
+- Whether the content should be a draft or scheduled.
+- Whether posts should be identical, platform-tailored, or threaded.
+
+When details are missing, make a reasonable draft and clearly mark assumptions before any live Postiz action.
+
+## Channel Fit
+
+Tailor content before scheduling:
+
+- X: short copy, hooks, thread structure, reply settings, and community settings when needed.
+- LinkedIn: professional framing, company/page selection, carousel settings when relevant.
+- Reddit: subreddit, title, flair, link/text type, and community norms.
+- YouTube or TikTok: title, description/caption, privacy, playlist, thumbnail, and AI-content declarations when required.
+- Instagram, Facebook, Threads, Bluesky, Mastodon, Medium, Dev.to, Hashnode, WordPress, Discord, Slack, Telegram, and other channels: check integration settings rather than guessing platform-specific fields.
+
+Use `postiz integrations:settings <integration-id>` to inspect the active schema for the user's connected channel.
+
+## Draft-First Pattern
+
+For non-trivial campaigns:
+
+1. Produce the candidate copy and media plan.
+2. Ask the user to approve or revise.
+3. Create drafts with `postiz posts:create -t draft`.
+4. List or inspect drafts if the user wants a final review.
+5. Promote drafts to scheduled posts only after confirmation.
+
+## JSON Posts
+
+Use JSON files for complex campaigns with multiple channels, comments, platform settings, or media. Keep the file in the workspace only when the user wants a durable artifact. Do not include API keys in JSON post files.
+
+Recommended JSON workflow:
+
+1. Build the JSON with placeholders for integration IDs until discovery is complete.
+2. Discover integration IDs and settings.
+3. Upload media and replace media placeholders with Postiz media paths.
+4. Ask for final review.
+5. Run `postiz posts:create --json <file>`.
+
+## Scheduling Safety
+
+Before scheduling, restate:
+
+- Target platforms.
+- Exact scheduled time with time zone.
+- Post type: draft or schedule.
+- Media assets and upload status.
+- Any platform-specific settings.
+
+If the user asked for "tomorrow" or another relative date, resolve it to an exact date before scheduling.
+
+## Analytics Follow-Up
+
+For performance reviews:
+
+1. Use platform analytics for channel-level trends.
+2. Use post analytics for content-specific performance.
+3. If analytics reports missing release data, follow the missing-release workflow in the `postiz-cli` skill.
+4. Summarize results in user-facing language. Avoid dumping raw analytics unless the user asks.
+
+## Avoid
+
+- Scheduling content without final user confirmation.
+- Guessing integration IDs or required platform settings.
+- Passing raw media paths to post creation commands.
+- Posting to broad groups or customer accounts without checking scope.
+- Persisting credentials, tokens, or API URLs without explicit approval.