openclaw-twitter-skill 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xiaoxi / OpenClaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,109 @@
+# OpenClaw Twitter Skill
+
+[![npm version](https://img.shields.io/npm/v/openclaw-twitter-skill.svg)](https://www.npmjs.com/package/openclaw-twitter-skill)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Stable, automated Twitter (X) posting skill for [OpenClaw](https://openclaw.ai) agents.
+
+## Problem
+
+OpenClaw agents can control Chrome via browser tools, but Twitter posting is unreliable — login checks fail, buttons don't get clicked, content gets lost. This skill standardizes the entire process into a battle-tested 5-step workflow.
+
+## The 5-Step Workflow
+
+```
+Step 1  →  Navigate to x.com/compose/post  (direct URL, never sidebar)
+Step 2  →  Verify login (compose box visible?)
+Step 3  →  Type content (type(), not paste)
+Step 4  →  Screenshot → user confirms content
+Step 5  →  Click Post → verify success toast
+```
+
+## Installation
+
+### As an OpenClaw Skill
+
+Copy `SKILL.md` to your agent's skills directory:
+
+```bash
+npm install -g openclaw-twitter-skill
+
+# Copy the skill file
+cp "$(npm root -g)/openclaw-twitter-skill/SKILL.md" ~/.agents/skills/twitter-post/SKILL.md
+```
+
+### CLI Usage
+
+```bash
+# Simulate the full posting workflow
+oct-post post "Hello from OpenClaw! 🚀 #AI #Automation"
+
+# Validate content against posting rules
+oct-post validate "Testing content #test #openclaw"
+
+# Dry run (validate only, don't mark as ready)
+oct-post post "Draft tweet #draft" --dry-run
+
+# Show workflow info
+oct-post info
+
+# Help
+oct-post --help
+```
+
+## Content Guidelines
+
+| Rule | Spec |
+|------|------|
+| Mode | New post only (no replies) |
+| Length | < 200 characters recommended (280 max) |
+| Emoji | 1–3, placed naturally |
+| Hashtags | 1–3 relevant tags (supports CJK: `#人工智能`) |
+| Links | Only if user explicitly provides them |
+| Media | Text-only by default; image upload requires user interaction |
+
+## Error Handling
+
+- **Not logged in** → Stop immediately, ask user to login in Chrome
+- **Post failed** → Screenshot + specific error description
+- **Never retry silently** → Always report what happened
+- **Never skip screenshot** → User must confirm before posting
+- **One retry max** → Only for server errors, with 30s wait
+
+## Key Lessons
+
+1. Always use `/compose/post` direct URL (sidebar buttons break across UI updates)
+2. Use `type()` not paste (Twitter CSP may block clipboard)
+3. Screenshot before posting (biggest reliability win)
+4. Wait 1–1.5s for Post button to enable after typing
+5. One post per session (don't chain without spacing)
+6. Check success toast, not URL change
+7. Use `snapshot()` for logic checks, `screenshot()` for user confirmation
+
+## Development
+
+```bash
+# Run tests
+npm test
+
+# Test CLI locally
+node index.js post "Test tweet #dev" --dry-run
+node index.js validate "Check this content #test"
+```
+
+## Release
+
+Push a version tag to trigger auto-release:
+
+```bash
+npm version patch   # or minor / major
+git push origin main --tags
+```
+
+GitHub Actions will:
+1. Create a GitHub Release with auto-generated notes
+2. Publish to NPM (requires `NPM_TOKEN` secret in repo settings)
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: twitter-post
+description: >
+  Stable automated Twitter (X) posting skill for OpenClaw agents.
+  Uses browser tools to navigate to x.com/compose/post, verify login,
+  type content, screenshot for confirmation, and click Post.
+  Use when: "发推", "tweet", "post to X", "发帖", "share on Twitter",
+  "推特发布", "帮我发一条推", or any social media posting request targeting X/Twitter.
+---
+
+# Twitter Post Skill
+
+Standardized 5-step workflow for OpenClaw agents to post on X (Twitter) via browser tools.
+
+## Prerequisites
+
+- The user must already be logged into x.com in the Chrome OpenClaw profile.
+- The agent must have access to `browser` tools (navigate, act, type, screenshot, snapshot, wait).
+
+## Quick Start
+
+When the user asks to post to Twitter, follow these steps **exactly in order**:
+
+```
+Step 1 → Open https://x.com/compose/post
+Step 2 → Verify login (is the compose box visible?)
+Step 3 → Type content into the compose box
+Step 4 → Screenshot → show user for confirmation
+Step 5 → Click Post → verify success
+```
+
+**CRITICAL RULES (read before proceeding):**
+- NEVER reply to an existing tweet — new post mode only.
+- NEVER post without showing the user a screenshot first.
+- NEVER retry silently on failure.
+- NEVER modify user's content without explicit permission.
+
+## Detailed Instructions
+
+### Step 1: Open Compose Page
+
+```javascript
+// ALWAYS use the direct compose URL — never click sidebar buttons
+await browser.navigate("https://x.com/compose/post");
+await browser.wait(3000); // wait for page load
+```
+
+**Why direct URL?** Twitter's sidebar UI changes frequently. The `/compose/post` modal route is the most stable entry point. Sidebar "Post" button, `Ctrl+Enter` shortcut, and floating action buttons all break across UI updates.
+
+### Step 2: Verify Login
+
+After navigation, take a snapshot to check page state:
+
+```javascript
+const snapshot = await browser.snapshot();
+// Examine the snapshot text for indicators below
+```
+
+**Check for these indicators:**
+
+| State | What you'll see in snapshot | Action |
+|-------|---------------------------|--------|
+| ✅ Logged in | `contenteditable` text area, "Post" button, character counter | Proceed to Step 3 |
+| ❌ Not logged in | "Sign in" / "Log in" text, email/password fields | **STOP** — report to user |
+| ⚠️ Rate limited | "Rate limit" / "Try again later" / error banner | **STOP** — screenshot and report |
+| ⚠️ Account suspended | "Your account is suspended" message | **STOP** — screenshot and report |
+
+**If not logged in, respond with:**
+> ⚠️ Twitter 未登录。请先在 Chrome OpenClaw profile 中手动登录 x.com，然后重试。
+
+Do NOT attempt to enter credentials or guess passwords. This is a hard stop.
+
+### Step 3: Type Content
+
+```javascript
+// Click the compose text area first to focus it
+await browser.act("click the tweet compose text area");
+await browser.wait(500);
+
+// Type the content character by character (do NOT paste)
+await browser.type("Your tweet content here #OpenClaw");
+await browser.wait(1000); // wait for content to settle
+```
+
+**Content rules (MUST follow):**
+
+| Rule | Spec |
+|------|------|
+| Mode | New post ONLY — never reply to existing tweets |
+| Length | Maximum 200 characters (leave room for rendering) |
+| Emoji | 1–3 emojis, placed naturally (not emoji spam) |
+| Hashtags | 1–3 relevant hashtags at the end |
+| Language | Match user's language preference |
+| Links | Only if the user explicitly provides them |
+| Media | Text-only by default (see Media Attachments section below) |
+
+**Content template:**
+```
+[Core message, 1-2 sentences] [1-2 emoji]
+
+#Tag1 #Tag2
+```
+
+**Why type() not paste?** Twitter's CSP and anti-bot measures may block clipboard paste events. `type()` simulates real keyboard input and is consistently more reliable.
+
+### Step 4: Screenshot for Confirmation
+
+```javascript
+// MANDATORY — never skip this step
+const screenshot = await browser.screenshot();
+```
+
+Present the screenshot to the user and say:
+> 📸 请确认推文内容是否正确。确认后我将点击发布。
+
+**Wait for user confirmation before proceeding.** If the user wants changes:
+1. Select all text in the compose box: `await browser.act("select all text in the compose area");`
+2. Delete it: `await browser.act("press Backspace");`
+3. Type the new content
+4. Screenshot again
+
+### Step 5: Click Post & Verify
+
+```javascript
+// Wait for the Post button to be enabled (it takes ~500ms-1s after typing)
+await browser.wait(1500);
+
+// Click the Post button
+await browser.act('click the "Post" button');
+
+// Wait for the post to be submitted
+await browser.wait(3000);
+
+// Take a verification screenshot
+const result = await browser.screenshot();
+```
+
+**Success indicators (check in screenshot/snapshot):**
+- "Your post was sent" toast notification at the bottom
+- Compose modal closes and returns to timeline
+- A "View" link appears in the toast
+
+**Failure indicators:**
+- Post button still visible → it wasn't clicked
+- "Something went wrong" toast → Twitter server error
+- Error popup / red text → content validation error
+- Page unchanged → JavaScript error, nothing happened
+
+**On success, respond:**
+> ✅ 推文已发布成功！
+
+**On failure, respond with screenshot:**
+> ❌ 发布失败。截图如上，请检查。[具体错误描述]
+
+## Media Attachments (Optional)
+
+If the user wants to attach an image:
+
+```javascript
+// After Step 3 (typing content), before Step 4 (screenshot):
+await browser.act('click the "Add photos or video" button (media icon)');
+await browser.wait(1000);
+// The file picker will open — this requires user interaction
+// Report to user: "请在弹出的文件选择器中选择要上传的图片"
+```
+
+**Limitations:**
+- File picker is a native OS dialog — the agent cannot select files programmatically.
+- Wait for the image to upload and thumbnail to appear before proceeding.
+- If no media button is found, proceed with text-only post.
+
+## Multi-Tweet Handling
+
+If the user provides multiple tweets to post:
+
+1. **Post them ONE AT A TIME** — complete the full 5-step cycle for each.
+2. **Wait at least 30 seconds between posts** to avoid rate limiting.
+3. **Get confirmation for each tweet separately** — do not batch confirmations.
+4. **If any tweet fails, STOP** — do not continue with remaining tweets.
+
+## Error Handling Rules
+
+1. **NEVER retry silently.** If posting fails, report the error with a screenshot immediately.
+2. **NEVER guess or fill in credentials.** Login is the user's responsibility.
+3. **NEVER post without user confirmation** (Step 4 screenshot approval).
+4. **NEVER modify the user's content** without telling them.
+5. **Report specific errors:** "Button disabled", "Page not loaded", "Rate limited" — not just "failed".
+6. **One retry maximum:** For "Something went wrong" server errors only, wait 30 seconds and retry the full workflow once. If it fails again, stop.
+
+## Common Failure Modes & Fixes
+
+| Problem | Cause | Fix |
+|---------|-------|-----|
+| Compose box not found | Page didn't fully load | `wait(5000)` then `snapshot()` to check again |
+| Post button disabled | Content empty or invalid | Verify text was actually typed via `snapshot()` |
+| "Something went wrong" | Twitter server error | Wait 30s, retry once, then report |
+| Page shows login form | Session expired | Ask user to re-login in Chrome profile |
+| Content truncated | Typed too fast | Add `wait(500)` between segments if content is long |
+| Modal doesn't open | URL didn't navigate properly | Try `navigate()` again with a fresh page load |
+| "Post" button not found | UI layout changed | Use `snapshot()` to find the actual button text/label |
+
+## Lessons Learned (经验教训)
+
+1. **`/compose/post` is king** — Sidebar "Post" button and keyboard shortcuts are unreliable across UI updates. Always navigate directly.
+2. **Type, don't paste** — `type()` simulates human input; paste may be blocked by Twitter's CSP.
+3. **Always screenshot before posting** — This is the single biggest reliability improvement. Users catch errors, and you have evidence of what was attempted.
+4. **Wait before clicking Post** — The Post button takes 500ms–1s to become active after content is entered. Clicking too early does nothing.
+5. **One post per session** — Don't chain multiple posts without spacing. Complete one full cycle before starting another.
+6. **Check toast, not URL** — After posting, the URL may not change immediately. Look for the success toast notification.
+7. **snapshot() over screenshot() for logic** — Use `snapshot()` (DOM text) for programmatic checks, `screenshot()` (image) for user-facing confirmation.
+8. **act() is your friend** — When specific selectors break, describe the action in natural language: `act('click the blue Post button')` is more robust than CSS selectors.

package/index.js

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+
+/**
+ * OpenClaw Twitter Skill CLI (oct-post)
+ *
+ * Provides a CLI interface for the standardized 5-step Twitter posting workflow.
+ * In standalone mode, this validates and previews the workflow.
+ * When used by an OpenClaw agent, the SKILL.md drives the actual browser execution.
+ *
+ * Zero dependencies — uses only Node.js built-in modules.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// ─── Helpers ───────────────────────────────────────────────
+
+const NO_COLOR = process.env.NO_COLOR || !process.stdout.isTTY;
+
+const C = NO_COLOR
+  ? { reset: '', red: '', green: '', yellow: '', cyan: '', dim: '', bold: '' }
+  : {
+      reset: '\x1b[0m',
+      red: '\x1b[31m',
+      green: '\x1b[32m',
+      yellow: '\x1b[33m',
+      cyan: '\x1b[36m',
+      dim: '\x1b[2m',
+      bold: '\x1b[1m',
+    };
+
+function log(icon, msg) { console.log(`${icon}  ${msg}`); }
+function ok(msg)   { log(`${C.green}✔${C.reset}`, msg); }
+function warn(msg) { log(`${C.yellow}⚠${C.reset}`, msg); }
+function fail(msg) { log(`${C.red}✖${C.reset}`, msg); }
+function info(msg) { log(`${C.cyan}ℹ${C.reset}`, msg); }
+function step(n, msg) { console.log(`\n${C.cyan}[Step ${n}/5]${C.reset} ${msg}`); }
+
+function getPkg() {
+  return JSON.parse(fs.readFileSync(path.join(__dirname, 'package.json'), 'utf-8'));
+}
+
+// ─── Content Validation ────────────────────────────────────
+
+/**
+ * Validate tweet content against posting rules.
+ * Returns { valid, errors[], warnings[], stats{} }
+ */
+function validateContent(text) {
+  const errors = [];
+  const warnings = [];
+
+  if (!text || text.trim().length === 0) {
+    errors.push('Content is empty.');
+    return { valid: false, errors, warnings, stats: {} };
+  }
+
+  const trimmed = text.trim();
+  const len = trimmed.length;
+
+  // Hashtags: support ASCII and Unicode word chars (CJK, etc.)
+  const hashtags = trimmed.match(/#[\w\u4e00-\u9fff\u3400-\u4dbf\uF900-\uFAFF]+/gu) || [];
+
+  // Emojis: broad Unicode emoji detection
+  const emojis = trimmed.match(
+    /[\u{1F600}-\u{1F9FF}\u{2600}-\u{26FF}\u{2700}-\u{27BF}\u{1F300}-\u{1F5FF}\u{1F680}-\u{1F6FF}\u{1F1E0}-\u{1F1FF}\u{1FA00}-\u{1FA6F}\u{1FA70}-\u{1FAFF}\u{2702}-\u{27B0}\u{FE00}-\u{FE0F}\u{200D}\u{20E3}]/gu
+  ) || [];
+
+  // Hard limit: Twitter's 280 chars
+  if (len > 280) {
+    errors.push(`Exceeds Twitter limit: ${len}/280 characters.`);
+  } else if (len > 200) {
+    warnings.push(`Content is ${len} chars. Recommended < 200 for readability.`);
+  }
+
+  // Hashtag guidance
+  if (hashtags.length > 3) {
+    warnings.push(`Too many hashtags (${hashtags.length}). Recommended 1–3.`);
+  } else if (hashtags.length === 0) {
+    warnings.push('No hashtags found. Consider adding 1–3 relevant tags.');
+  }
+
+  // Emoji guidance
+  if (emojis.length > 5) {
+    warnings.push(`Many emojis (${emojis.length}). Recommended 1–3.`);
+  }
+
+  // Check for potential reply patterns
+  if (trimmed.startsWith('@')) {
+    warnings.push('Content starts with @mention — this may create a reply instead of a new post.');
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings,
+    stats: { length: len, hashtags: hashtags.length, emojis: emojis.length },
+  };
+}
+
+// Expose for testing
+module.exports = { validateContent };
+
+// ─── Commands ──────────────────────────────────────────────
+
+function cmdPost(content, opts) {
+  console.log(`\n${'─'.repeat(50)}`);
+  console.log(`  🐦  OpenClaw Twitter Posting Workflow`);
+  console.log(`${'─'.repeat(50)}`);
+
+  const result = validateContent(content);
+
+  if (!result.valid) {
+    result.errors.forEach(e => fail(e));
+    process.exit(1);
+  }
+  result.warnings.forEach(w => warn(w));
+
+  info(`Content: ${result.stats.length} chars | ${result.stats.hashtags} hashtags | ${result.stats.emojis} emojis`);
+
+  step(1, 'Navigate to https://x.com/compose/post');
+  ok('Open compose page');
+
+  step(2, 'Verify login status');
+  ok('Check for compose text area');
+
+  step(3, 'Type content');
+  console.log(`${C.dim}   "${content}"${C.reset}`);
+  ok('Content entered');
+
+  step(4, 'Screenshot for confirmation');
+  if (opts.skipConfirm) {
+    warn('--skip-confirm: Skipping user confirmation (use with caution)');
+  } else {
+    ok('Screenshot taken → awaiting user confirmation');
+  }
+
+  step(5, 'Click Post & verify');
+  ok('Click "Post" button → check success toast');
+
+  console.log(`\n${'─'.repeat(50)}`);
+  if (opts.dryRun) {
+    warn('DRY RUN — No actual posting. Workflow validated successfully.');
+  } else {
+    ok('Workflow ready. Agent will execute via browser tools.');
+  }
+  console.log(`${'─'.repeat(50)}\n`);
+}
+
+function cmdValidate(content) {
+  console.log('\n🔍 Validating tweet content...\n');
+  const result = validateContent(content);
+
+  if (result.valid) {
+    ok('Content is valid');
+  } else {
+    result.errors.forEach(e => fail(e));
+  }
+  result.warnings.forEach(w => warn(w));
+
+  console.log(`\n📊 Stats:`);
+  console.log(`   Length:   ${result.stats.length}/280 (recommended < 200)`);
+  console.log(`   Hashtags: ${result.stats.hashtags} (recommended 1–3)`);
+  console.log(`   Emojis:   ${result.stats.emojis} (recommended 1–3)`);
+
+  process.exit(result.valid ? 0 : 1);
+}
+
+function cmdInfo() {
+  const pkg = getPkg();
+  console.log(`\n🐦  ${C.bold}${pkg.name}${C.reset} v${pkg.version}`);
+  console.log(`   ${pkg.description}\n`);
+  console.log(`${C.bold}Workflow:${C.reset} 5-step standardized posting`);
+  console.log('  1. Open  → https://x.com/compose/post');
+  console.log('  2. Login → verify compose box visible');
+  console.log('  3. Type  → enter content (< 200 chars)');
+  console.log('  4. Shot  → screenshot for user confirmation');
+  console.log('  5. Post  → click button & verify success\n');
+  console.log(`${C.dim}Homepage: ${pkg.homepage}${C.reset}`);
+}
+
+// ─── CLI Parsing (zero-dependency) ─────────────────────────
+
+function printHelp() {
+  const pkg = getPkg();
+  console.log(`
+${C.bold}${pkg.name}${C.reset} v${pkg.version}
+
+${C.bold}USAGE${C.reset}
+  oct-post <command> [options]
+
+${C.bold}COMMANDS${C.reset}
+  post <content>       Simulate the 5-step posting workflow
+  validate <content>   Validate tweet content against rules
+  info                 Show skill info and workflow summary
+
+${C.bold}OPTIONS${C.reset}
+  --dry-run            Validate only, don't mark as ready to post
+  --skip-confirm       Skip screenshot confirmation step
+  -h, --help           Show this help message
+  -v, --version        Show version number
+
+${C.bold}EXAMPLES${C.reset}
+  oct-post post "Hello from OpenClaw! 🚀 #AI #Automation"
+  oct-post post "Draft tweet #draft" --dry-run
+  oct-post validate "Testing content #test"
+  oct-post info
+`);
+}
+
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (args[0] === '--version' || args[0] === '-v') {
+    console.log(getPkg().version);
+    process.exit(0);
+  }
+
+  const cmd = args[0];
+
+  switch (cmd) {
+    case 'post': {
+      const content = args.find((a, i) => i > 0 && !a.startsWith('--'));
+      if (!content) {
+        fail('Missing content. Usage: oct-post post "your tweet"');
+        process.exit(1);
+      }
+      cmdPost(content, {
+        dryRun: args.includes('--dry-run'),
+        skipConfirm: args.includes('--skip-confirm'),
+      });
+      break;
+    }
+    case 'validate': {
+      const content = args.find((a, i) => i > 0 && !a.startsWith('--'));
+      if (!content) {
+        fail('Missing content. Usage: oct-post validate "your tweet"');
+        process.exit(1);
+      }
+      cmdValidate(content);
+      break;
+    }
+    case 'info':
+      cmdInfo();
+      break;
+    default:
+      fail(`Unknown command: ${cmd}`);
+      printHelp();
+      process.exit(1);
+  }
+}
+
+// Only run CLI when executed directly (not when require'd for testing)
+if (require.main === module) {
+  main();
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "openclaw-twitter-skill",
+  "version": "1.2.0",
+  "description": "OpenClaw agent skill for stable automated Twitter (X) posting via browser tools. Standardized 5-step workflow with login check, content validation, screenshot confirmation, and error reporting.",
+  "main": "index.js",
+  "bin": {
+    "oct-post": "index.js"
+  },
+  "files": [
+    "index.js",
+    "SKILL.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node tests/test.js",
+    "prepublishOnly": "node tests/test.js"
+  },
+  "keywords": [
+    "openclaw",
+    "twitter",
+    "x",
+    "automation",
+    "skill",
+    "agent",
+    "browser",
+    "social-media",
+    "posting"
+  ],
+  "author": "xiaoxi <xiaoxi@openclaw.ai>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adminlove520/openclaw-twitter-skill.git"
+  },
+  "homepage": "https://github.com/adminlove520/openclaw-twitter-skill#readme",
+  "bugs": {
+    "url": "https://github.com/adminlove520/openclaw-twitter-skill/issues"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}