Add Hermes Tweet skill

.claude-plugin/marketplace.json

@@ -59,6 +59,25 @@
         "perplexity"
       ]
     },
+    {
+      "name": "hermes-tweet",
+      "description": "Use Hermes Agent with Xquik for X/Twitter search, social listening, account reads, trend checks, and approval-gated posting or account actions.",
+      "source": "./dist/plugins/hermes-tweet",
+      "strict": false,
+      "skills": [
+        "./skills/hermes-tweet"
+      ],
+      "category": "ai-tools",
+      "keywords": [
+        "ai",
+        "hermes-agent",
+        "xquik",
+        "twitter",
+        "x",
+        "social-media",
+        "automation"
+      ]
+    },
     {
       "name": "agent-md-refactor",
       "description": "Refactor bloated AGENTS.md, CLAUDE.md, or similar agent instruction files to follow progressive disclosure principles. Splits monolithic files into organized, linked documentation.",

README.md

@@ -98,6 +98,7 @@ Add skills to project knowledge or paste SKILL.md contents into the conversation
 |----------|-------|-------------|
 | 🤖 AI Tools | [codex](skills/codex/README.md) | Advanced code analysis with GPT-5.2 |
 | 🤖 AI Tools | [gemini](skills/gemini/README.md) | Large-scale review (200k+ context) |
+| 🤖 AI Tools | [hermes-tweet](skills/hermes-tweet/README.md) | Hermes Agent X/Twitter automation |
 | 🤖 AI Tools | [perplexity](skills/perplexity/README.md) | Web search & research |
 | 🔮 Meta | [agent-md-refactor](skills/agent-md-refactor/README.md) | Refactor bloated agent instruction files |
 | 🔮 Meta | [command-creator](skills/command-creator/README.md) | Create Claude Code slash commands |

dist/plugins/hermes-tweet/skills/hermes-tweet/README.md

@@ -0,0 +1,55 @@
+# Hermes Tweet
+
+Hermes Tweet is a native Hermes Agent plugin for X automation through Xquik. It
+adds read-first X/Twitter workflows, social listening, account reads, trend
+checks, and approval-gated account actions to Hermes sessions.
+
+## When to Use
+
+Use this skill when a Hermes Agent workflow needs:
+
+- X/Twitter search and trend research
+- Social listening or launch monitoring
+- Account, tweet, follower, media, and timeline reads
+- Controlled posting, replies, likes, retweets, follows, DMs, monitors, webhooks, media, extraction jobs, or giveaway draws
+- A clear safety split between read-only work and account-changing actions
+
+## Install
+
+Install and enable the Hermes plugin:
+
+```bash
+hermes plugins install Xquik-dev/hermes-tweet --enable
+```
+
+Or install the published Python package into the Hermes environment:
+
+```bash
+uv pip install --python ~/.hermes/hermes-agent/venv/bin/python hermes-tweet
+hermes plugins enable hermes-tweet
+```
+
+Set `XQUIK_API_KEY` in the Hermes runtime environment for authenticated reads.
+Set `HERMES_TWEET_ENABLE_ACTIONS=true` only in sessions that intentionally allow
+account-changing actions.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `tweet_explore` | Search the endpoint catalog without an API call. |
+| `tweet_read` | Call catalog-listed read-only endpoints. |
+| `tweet_action` | Call write-like or private endpoints after explicit approval. |
+
+## Safety Defaults
+
+- Start every workflow with `tweet_explore`.
+- Prefer `tweet_read` for unattended or scheduled work.
+- Keep `tweet_action` disabled unless the user approves the exact operation.
+- Never ask users to paste API keys or other credentials into chat.
+- Use only catalog-listed `/api/v1/...` paths.
+
+## Reference
+
+- Repository: https://github.com/Xquik-dev/hermes-tweet
+- Package: https://pypi.org/project/hermes-tweet/

dist/plugins/hermes-tweet/skills/hermes-tweet/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: hermes-tweet
+description: Use Hermes Tweet when a Hermes Agent session needs X/Twitter search, social listening, account reads, trend checks, controlled posting, DMs, follows, monitors, webhooks, media, draws, or other approval-gated Xquik actions.
+metadata:
+  version: 0.1.6
+  author: Xquik
+  tags:
+    - hermes-agent
+    - xquik
+    - twitter
+    - x
+    - social-media
+    - automation
+---
+
+# Hermes Tweet
+
+Hermes Tweet is a native Hermes Agent plugin for X automation through Xquik. It
+exposes X/Twitter endpoint discovery, authenticated reads, and explicitly gated
+actions as Hermes tools.
+
+Use this skill only when the user is working in Hermes Agent or asks for Hermes
+Tweet, Xquik, X/Twitter automation, social listening, trend research, account
+checks, controlled posting, DMs, follows, monitors, webhooks, media, extraction
+jobs, or giveaway draws through Hermes.
+
+## Requirements
+
+- Hermes Agent with the `hermes-tweet` plugin installed and enabled.
+- `XQUIK_API_KEY` configured in the Hermes runtime environment for authenticated reads.
+- `HERMES_TWEET_ENABLE_ACTIONS=true` only for sessions that intentionally allow account-changing actions.
+
+Recommended install:
+
+```bash
+hermes plugins install Xquik-dev/hermes-tweet --enable
+```
+
+If the Python package is installed directly into the Hermes environment:
+
+```bash
+uv pip install --python ~/.hermes/hermes-agent/venv/bin/python hermes-tweet
+hermes plugins enable hermes-tweet
+```
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `tweet_explore` | Search the bundled Xquik endpoint catalog without making an API call. |
+| `tweet_read` | Call catalog-listed read-only endpoints after `XQUIK_API_KEY` is configured. |
+| `tweet_action` | Call write-like or private endpoints only when actions are enabled and approved. |
+
+## Workflow
+
+1. Start with `tweet_explore` to find a catalog-listed `/api/v1/...` endpoint.
+2. Use `tweet_read` for public or authenticated read-only endpoints.
+3. Use `tweet_action` only for writes, private reads, monitors, webhooks, media, extraction jobs, draws, DMs, follows, likes, retweets, replies, or posting after the user approves the exact operation.
+4. Summarize the selected endpoint and payload before any account-changing action.
+
+## Decision Rules
+
+- If the task is endpoint discovery, call `tweet_explore` with a short query.
+- If the matched endpoint is a read-only `GET` route, call `tweet_read`.
+- If the matched endpoint writes data or touches private account state, call `tweet_action` only after explicit approval.
+- If `tweet_action` is unavailable, explain that actions are intentionally gated by `HERMES_TWEET_ENABLE_ACTIONS=true`.
+- If `XQUIK_API_KEY` is missing, ask the user to configure it in the Hermes runtime environment. Do not ask them to paste the key into chat.
+- If Hermes lists the plugin as not enabled, tell the user to run `hermes plugins enable hermes-tweet` or reinstall with `--enable`.
+- If the user uses Hermes Desktop with a remote gateway profile, remind them that the plugin and environment variables must be configured on the remote Hermes host where plugin code runs.
+
+## Safety
+
+- Never request, echo, store, or pass API keys, passwords, cookies, signing keys, or TOTP secrets in tool arguments.
+- Do not guess endpoint paths. Use only endpoints returned by `tweet_explore`.
+- Do not create direct HTTP fallbacks around Hermes Tweet tools.
+- Keep `tweet_action` disabled for unattended, scheduled, gateway-driven, or cron-driven workflows unless the workflow has a clear approval step.
+- Do not use billing, account re-authentication, support-ticket, or API-key management routes.
+- Stop after policy, auth, or account-state failures instead of retrying through alternate routes.
+
+## Examples
+
+Search tweets:
+
+```json
+{"query":"tweet search","method":"GET"}
+```
+
+Then call `tweet_read`:
+
+```json
+{"path":"/api/v1/x/tweets/search","query":{"q":"AI agents","limit":25}}
+```
+
+Post a user-approved tweet:
+
+```json
+{"query":"post tweet","include_actions":true}
+```
+
+Then call `tweet_action`:
+
+```json
+{"path":"/api/v1/x/tweets","method":"POST","body":{"account":"@example","text":"Hello from Hermes Tweet"},"reason":"Post the user-approved tweet."}
+```
+
+## Verification
+
+After install or upgrade:
+
+1. Run `hermes plugins list` and confirm `hermes-tweet` is enabled.
+2. Run `hermes tools list` and confirm the `hermes-tweet` toolset is available.
+3. Confirm `tweet_explore` is available without `XQUIK_API_KEY`.
+4. Confirm `tweet_read` appears only after `XQUIK_API_KEY` is configured.
+5. Confirm `tweet_action` remains hidden or disabled unless `HERMES_TWEET_ENABLE_ACTIONS=true`.
+
+Reference: https://github.com/Xquik-dev/hermes-tweet

skills/hermes-tweet/README.md

@@ -0,0 +1,55 @@
+# Hermes Tweet
+
+Hermes Tweet is a native Hermes Agent plugin for X automation through Xquik. It
+adds read-first X/Twitter workflows, social listening, account reads, trend
+checks, and approval-gated account actions to Hermes sessions.
+
+## When to Use
+
+Use this skill when a Hermes Agent workflow needs:
+
+- X/Twitter search and trend research
+- Social listening or launch monitoring
+- Account, tweet, follower, media, and timeline reads
+- Controlled posting, replies, likes, retweets, follows, DMs, monitors, webhooks, media, extraction jobs, or giveaway draws
+- A clear safety split between read-only work and account-changing actions
+
+## Install
+
+Install and enable the Hermes plugin:
+
+```bash
+hermes plugins install Xquik-dev/hermes-tweet --enable
+```
+
+Or install the published Python package into the Hermes environment:
+
+```bash
+uv pip install --python ~/.hermes/hermes-agent/venv/bin/python hermes-tweet
+hermes plugins enable hermes-tweet
+```
+
+Set `XQUIK_API_KEY` in the Hermes runtime environment for authenticated reads.
+Set `HERMES_TWEET_ENABLE_ACTIONS=true` only in sessions that intentionally allow
+account-changing actions.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `tweet_explore` | Search the endpoint catalog without an API call. |
+| `tweet_read` | Call catalog-listed read-only endpoints. |
+| `tweet_action` | Call write-like or private endpoints after explicit approval. |
+
+## Safety Defaults
+
+- Start every workflow with `tweet_explore`.
+- Prefer `tweet_read` for unattended or scheduled work.
+- Keep `tweet_action` disabled unless the user approves the exact operation.
+- Never ask users to paste API keys or other credentials into chat.
+- Use only catalog-listed `/api/v1/...` paths.
+
+## Reference
+
+- Repository: https://github.com/Xquik-dev/hermes-tweet
+- Package: https://pypi.org/project/hermes-tweet/

skills/hermes-tweet/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: hermes-tweet
+description: Use Hermes Tweet when a Hermes Agent session needs X/Twitter search, social listening, account reads, trend checks, controlled posting, DMs, follows, monitors, webhooks, media, draws, or other approval-gated Xquik actions.
+metadata:
+  version: 0.1.6
+  author: Xquik
+  tags:
+    - hermes-agent
+    - xquik
+    - twitter
+    - x
+    - social-media
+    - automation
+---
+
+# Hermes Tweet
+
+Hermes Tweet is a native Hermes Agent plugin for X automation through Xquik. It
+exposes X/Twitter endpoint discovery, authenticated reads, and explicitly gated
+actions as Hermes tools.
+
+Use this skill only when the user is working in Hermes Agent or asks for Hermes
+Tweet, Xquik, X/Twitter automation, social listening, trend research, account
+checks, controlled posting, DMs, follows, monitors, webhooks, media, extraction
+jobs, or giveaway draws through Hermes.
+
+## Requirements
+
+- Hermes Agent with the `hermes-tweet` plugin installed and enabled.
+- `XQUIK_API_KEY` configured in the Hermes runtime environment for authenticated reads.
+- `HERMES_TWEET_ENABLE_ACTIONS=true` only for sessions that intentionally allow account-changing actions.
+
+Recommended install:
+
+```bash
+hermes plugins install Xquik-dev/hermes-tweet --enable
+```
+
+If the Python package is installed directly into the Hermes environment:
+
+```bash
+uv pip install --python ~/.hermes/hermes-agent/venv/bin/python hermes-tweet
+hermes plugins enable hermes-tweet
+```
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `tweet_explore` | Search the bundled Xquik endpoint catalog without making an API call. |
+| `tweet_read` | Call catalog-listed read-only endpoints after `XQUIK_API_KEY` is configured. |
+| `tweet_action` | Call write-like or private endpoints only when actions are enabled and approved. |
+
+## Workflow
+
+1. Start with `tweet_explore` to find a catalog-listed `/api/v1/...` endpoint.
+2. Use `tweet_read` for public or authenticated read-only endpoints.
+3. Use `tweet_action` only for writes, private reads, monitors, webhooks, media, extraction jobs, draws, DMs, follows, likes, retweets, replies, or posting after the user approves the exact operation.
+4. Summarize the selected endpoint and payload before any account-changing action.
+
+## Decision Rules
+
+- If the task is endpoint discovery, call `tweet_explore` with a short query.
+- If the matched endpoint is a read-only `GET` route, call `tweet_read`.
+- If the matched endpoint writes data or touches private account state, call `tweet_action` only after explicit approval.
+- If `tweet_action` is unavailable, explain that actions are intentionally gated by `HERMES_TWEET_ENABLE_ACTIONS=true`.
+- If `XQUIK_API_KEY` is missing, ask the user to configure it in the Hermes runtime environment. Do not ask them to paste the key into chat.
+- If Hermes lists the plugin as not enabled, tell the user to run `hermes plugins enable hermes-tweet` or reinstall with `--enable`.
+- If the user uses Hermes Desktop with a remote gateway profile, remind them that the plugin and environment variables must be configured on the remote Hermes host where plugin code runs.
+
+## Safety
+
+- Never request, echo, store, or pass API keys, passwords, cookies, signing keys, or TOTP secrets in tool arguments.
+- Do not guess endpoint paths. Use only endpoints returned by `tweet_explore`.
+- Do not create direct HTTP fallbacks around Hermes Tweet tools.
+- Keep `tweet_action` disabled for unattended, scheduled, gateway-driven, or cron-driven workflows unless the workflow has a clear approval step.
+- Do not use billing, account re-authentication, support-ticket, or API-key management routes.
+- Stop after policy, auth, or account-state failures instead of retrying through alternate routes.
+
+## Examples
+
+Search tweets:
+
+```json
+{"query":"tweet search","method":"GET"}
+```
+
+Then call `tweet_read`:
+
+```json
+{"path":"/api/v1/x/tweets/search","query":{"q":"AI agents","limit":25}}
+```
+
+Post a user-approved tweet:
+
+```json
+{"query":"post tweet","include_actions":true}
+```
+
+Then call `tweet_action`:
+
+```json
+{"path":"/api/v1/x/tweets","method":"POST","body":{"account":"@example","text":"Hello from Hermes Tweet"},"reason":"Post the user-approved tweet."}
+```
+
+## Verification
+
+After install or upgrade:
+
+1. Run `hermes plugins list` and confirm `hermes-tweet` is enabled.
+2. Run `hermes tools list` and confirm the `hermes-tweet` toolset is available.
+3. Confirm `tweet_explore` is available without `XQUIK_API_KEY`.
+4. Confirm `tweet_read` appears only after `XQUIK_API_KEY` is configured.
+5. Confirm `tweet_action` remains hidden or disabled unless `HERMES_TWEET_ENABLE_ACTIONS=true`.
+
+Reference: https://github.com/Xquik-dev/hermes-tweet