From f05309eb67f4dffce88190e63e401ed78ade2143 Mon Sep 17 00:00:00 2001 From: Saoud Rizwan <7799382+saoudrizwan@users.noreply.github.com> Date: Tue, 16 Jun 2026 08:46:19 -0700 Subject: [PATCH 1/2] feat: add postiz plugin --- README.md | 1 + plugins/postiz/README.md | 38 ++++++ plugins/postiz/index.ts | 26 ++++ plugins/postiz/package.json | 20 +++ plugins/postiz/skills/postiz-cli/SKILL.md | 116 ++++++++++++++++++ plugins/postiz/skills/postiz-content/SKILL.md | 84 +++++++++++++ 6 files changed, 285 insertions(+) create mode 100644 plugins/postiz/README.md create mode 100644 plugins/postiz/index.ts create mode 100644 plugins/postiz/package.json create mode 100644 plugins/postiz/skills/postiz-cli/SKILL.md create mode 100644 plugins/postiz/skills/postiz-content/SKILL.md diff --git a/README.md b/README.md index a400e81c..a762af1e 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,7 @@ Each plugin lives in `plugins/`. 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. | diff --git a/plugins/postiz/README.md b/plugins/postiz/README.md new file mode 100644 index 00000000..85c0772d --- /dev/null +++ b/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. The plugin also adds a safety rule for social posting side effects. + +## 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. diff --git a/plugins/postiz/index.ts b/plugins/postiz/index.ts new file mode 100644 index 00000000..9bfcc39e --- /dev/null +++ b/plugins/postiz/index.ts @@ -0,0 +1,26 @@ +import type { AgentPlugin } from "@cline/sdk" + +const rule = [ + "Postiz operations can publish, schedule, edit, delete, or analyze content across connected social accounts.", + "When using Postiz, verify authentication before API work, keep API keys and OAuth credentials out of chat and commits, and ask before persisting any credential.", + "Ask before running `postiz auth:login` because the device flow stores OAuth credentials in the user's home directory.", + "Ask for explicit user confirmation before creating scheduled posts, promoting drafts to scheduled posts, deleting posts, changing post status, connecting missing platform content, or uploading user media.", + "Never pass a raw local file path or arbitrary external URL as post media. Upload media with the user's Postiz CLI first and use the returned Postiz media URL/path.", + "Treat integration IDs, group IDs, platform settings, analytics exports, and post content as user data. Avoid broad exports or account-wide changes unless the user asked for that scope.", +].join("\n") + +const plugin: AgentPlugin = { + name: "postiz", + manifest: { + capabilities: ["skills", "rules"], + }, + setup(api) { + api.registerRule({ + id: "postiz-safety", + source: "postiz", + content: rule, + }) + }, +} + +export default plugin diff --git a/plugins/postiz/package.json b/plugins/postiz/package.json new file mode 100644 index 00000000..24fb1a0c --- /dev/null +++ b/plugins/postiz/package.json @@ -0,0 +1,20 @@ +{ + "name": "postiz", + "version": "0.0.0", + "private": true, + "type": "module", + "description": "Cline plugin with Postiz social media scheduling skills and safety rules.", + "cline": { + "plugins": [ + { + "paths": [ + "./index.ts" + ], + "capabilities": [ + "skills", + "rules" + ] + } + ] + } +} diff --git a/plugins/postiz/skills/postiz-cli/SKILL.md b/plugins/postiz/skills/postiz-cli/SKILL.md new file mode 100644 index 00000000..42a1c535 --- /dev/null +++ b/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 `. +3. Fetch dynamic platform data with `postiz integrations:trigger ` when the settings mention required lookup data. +4. Upload media with `postiz upload ` 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 +postiz integrations:trigger -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 --status draft +postiz posts:status --status schedule +postiz posts:delete +``` + +Analytics: + +```bash +postiz analytics:platform -d 30 +postiz analytics:post -d 30 +postiz posts:missing +postiz posts:connect --release-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 ` reports missing content: + +1. Run `postiz posts:missing `. +2. Show the candidate platform content to the user. +3. Ask which item to connect. +4. Run `postiz posts:connect --release-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 `. +- Media errors should route back to `postiz upload`. +- Shell quoting errors are common with JSON settings. Prefer JSON files for complex multi-platform posts. diff --git a/plugins/postiz/skills/postiz-content/SKILL.md b/plugins/postiz/skills/postiz-content/SKILL.md new file mode 100644 index 00000000..6e9d7e67 --- /dev/null +++ b/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 ` 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 `. + +## 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. From a2b4a0bca76b2090f170ee2ef1edf9f56b74e259 Mon Sep 17 00:00:00 2001 From: Saoud Rizwan <7799382+saoudrizwan@users.noreply.github.com> Date: Wed, 17 Jun 2026 19:20:10 -0700 Subject: [PATCH 2/2] fix: remove extra postiz rule primitive --- plugins/postiz/README.md | 2 +- plugins/postiz/index.ts | 18 +----------------- plugins/postiz/package.json | 5 ++--- 3 files changed, 4 insertions(+), 21 deletions(-) diff --git a/plugins/postiz/README.md b/plugins/postiz/README.md index 85c0772d..5dec35dc 100644 --- a/plugins/postiz/README.md +++ b/plugins/postiz/README.md @@ -4,7 +4,7 @@ Postiz workflow guidance for Cline. It helps agents plan and execute social medi ## What It Does -Installs skills for Postiz setup, integration discovery, content scheduling, media upload, platform settings, and analytics triage. The plugin also adds a safety rule for social posting side effects. +Installs skills for Postiz setup, integration discovery, content scheduling, media upload, platform settings, and analytics triage. ## Install diff --git a/plugins/postiz/index.ts b/plugins/postiz/index.ts index 9bfcc39e..72e4688a 100644 --- a/plugins/postiz/index.ts +++ b/plugins/postiz/index.ts @@ -1,25 +1,9 @@ import type { AgentPlugin } from "@cline/sdk" -const rule = [ - "Postiz operations can publish, schedule, edit, delete, or analyze content across connected social accounts.", - "When using Postiz, verify authentication before API work, keep API keys and OAuth credentials out of chat and commits, and ask before persisting any credential.", - "Ask before running `postiz auth:login` because the device flow stores OAuth credentials in the user's home directory.", - "Ask for explicit user confirmation before creating scheduled posts, promoting drafts to scheduled posts, deleting posts, changing post status, connecting missing platform content, or uploading user media.", - "Never pass a raw local file path or arbitrary external URL as post media. Upload media with the user's Postiz CLI first and use the returned Postiz media URL/path.", - "Treat integration IDs, group IDs, platform settings, analytics exports, and post content as user data. Avoid broad exports or account-wide changes unless the user asked for that scope.", -].join("\n") - const plugin: AgentPlugin = { name: "postiz", manifest: { - capabilities: ["skills", "rules"], - }, - setup(api) { - api.registerRule({ - id: "postiz-safety", - source: "postiz", - content: rule, - }) + capabilities: ["skills"], }, } diff --git a/plugins/postiz/package.json b/plugins/postiz/package.json index 24fb1a0c..27c874d9 100644 --- a/plugins/postiz/package.json +++ b/plugins/postiz/package.json @@ -3,7 +3,7 @@ "version": "0.0.0", "private": true, "type": "module", - "description": "Cline plugin with Postiz social media scheduling skills and safety rules.", + "description": "Cline plugin with Postiz social media scheduling skills.", "cline": { "plugins": [ { @@ -11,8 +11,7 @@ "./index.ts" ], "capabilities": [ - "skills", - "rules" + "skills" ] } ]