diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 28a8124..48d2173 100644 --- a/.claude-plugin/marketplace.json +++ b/.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.", diff --git a/README.md b/README.md index dd457d8..e9ac2d4 100644 --- a/README.md +++ b/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 | diff --git a/dist/plugins/hermes-tweet/skills/hermes-tweet/README.md b/dist/plugins/hermes-tweet/skills/hermes-tweet/README.md new file mode 100644 index 0000000..104ae01 --- /dev/null +++ b/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/ diff --git a/dist/plugins/hermes-tweet/skills/hermes-tweet/SKILL.md b/dist/plugins/hermes-tweet/skills/hermes-tweet/SKILL.md new file mode 100644 index 0000000..6bde053 --- /dev/null +++ b/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 diff --git a/skills/hermes-tweet/README.md b/skills/hermes-tweet/README.md new file mode 100644 index 0000000..104ae01 --- /dev/null +++ b/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/ diff --git a/skills/hermes-tweet/SKILL.md b/skills/hermes-tweet/SKILL.md new file mode 100644 index 0000000..6bde053 --- /dev/null +++ b/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