schwepps · kriptoburak · Jun 12, 2026
diff --git a/.claude-plugin/marketplace-tooling.json b/.claude-plugin/marketplace-tooling.json
@@ -4,18 +4,25 @@
     "url": "https://github.com/schwepps"
   },
   "name": "skills-tooling",
-  "version": "1.0.0",
-  "description": "Developer tools and automation skills for Claude Code.",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/schwepps/skills.git"
+  "metadata": {
+    "version": "1.0.0",
+    "description": "Developer tools and automation skills for Claude Code.",
+    "license": "MIT",
+    "repository": {
+      "type": "git",
+      "url": "https://github.com/schwepps/skills.git"
+    }
   },
   "plugins": [
     {
       "name": "install-skill",
       "source": "./install-skill",
       "description": "Automate skill package installation and marketplace registration"
+    },
+    {
+      "name": "hermes-tweet",
+      "source": "./hermes-tweet",
+      "description": "Hermes Agent X/Twitter plugin setup and guarded operation"
     }
   ]
 }
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -4,12 +4,14 @@
     "url": "https://github.com/schwepps"
   },
   "name": "skills",
-  "version": "1.0.0",
-  "description": "Claude Code skills: SEO audits, AI search optimization, music creation, smart contract security, LinkedIn personal branding, developer tools.",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/schwepps/skills.git"
+  "metadata": {
+    "version": "1.0.0",
+    "description": "Claude Code skills: SEO audits, AI search optimization, music creation, smart contract security, LinkedIn personal branding, developer tools.",
+    "license": "MIT",
+    "repository": {
+      "type": "git",
+      "url": "https://github.com/schwepps/skills.git"
+    }
   },
   "plugins": [
     {
@@ -51,6 +53,11 @@
       "name": "linkedin-roast",
       "source": "./linkedin-roast",
       "description": "LinkedIn profile roasting with savage but friendly comedy burns"
+    },
+    {
+      "name": "hermes-tweet",
+      "source": "./hermes-tweet",
+      "description": "Hermes Agent X/Twitter plugin setup and guarded operation"
     }
   ]
 }
diff --git a/README.md b/README.md
@@ -2,7 +2,7 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**Documentation-based skills** for Claude Code, Claude Desktop, and any AI tool supporting skills. Specialized workflows for SEO audits, AI search optimization, music creation, smart contract security, LinkedIn personal branding, LinkedIn roasts, and developer tools.
+**Documentation-based skills** for Claude Code, Claude Desktop, and any AI tool supporting skills. Specialized workflows for SEO audits, AI search optimization, music creation, smart contract security, LinkedIn personal branding, LinkedIn roasts, Hermes Agent social tooling, and developer tools.
 
 ---
 
@@ -34,6 +34,7 @@ Find packaged skills in `dist/`, then add to your tool's skills directory.
 | **[install-skill](install-skill/)** | Automate skill package installation and marketplace registration |
 | **[linkedin-personal-branding](linkedin-personal-branding/)** | LinkedIn profile analysis, personal branding audit, and visibility optimization |
 | **[linkedin-roast](linkedin-roast/)** | Hilarious LinkedIn profile roasting with savage but friendly comedy burns |
+| **[hermes-tweet](hermes-tweet/)** | Hermes Agent X/Twitter plugin setup and guarded operation |
 
 ## Usage Examples
 
@@ -71,6 +72,9 @@ Find packaged skills in `dist/`, then add to your tool's skills directory.
 "Install the skill from dist/my-skill.skill"
 "Add a new skill to the marketplace"
 "Unpack and register this skill package"
+"Install Hermes Tweet for Hermes Agent"
+"Configure XQUIK_API_KEY for tweet_read"
+"Enable tweet_action only after I approve the post"
 ```
 
 ## How Skills Work
@@ -114,6 +118,7 @@ Download individual skills directly as ZIP files - no git or command line needed
 | Install Skill | [Download ZIP](https://download-directory.github.io/?url=https://github.com/schwepps/skills/tree/main/install-skill) |
 | LinkedIn Personal Branding | [Download ZIP](https://download-directory.github.io/?url=https://github.com/schwepps/skills/tree/main/linkedin-personal-branding) |
 | LinkedIn Roast | [Download ZIP](https://download-directory.github.io/?url=https://github.com/schwepps/skills/tree/main/linkedin-roast) |
+| Hermes Tweet | [Download ZIP](https://download-directory.github.io/?url=https://github.com/schwepps/skills/tree/main/hermes-tweet) |
 
 *Powered by [download-directory.github.io](https://download-directory.github.io)*
 
@@ -122,7 +127,8 @@ Download individual skills directly as ZIP files - no git or command line needed
 ```
 skills/
 ├── .claude-plugin/
-│   └── marketplace.json     # Skill registry
+│   ├── marketplace.json     # Skill registry
+│   └── marketplace-tooling.json
 ├── scripts/
 │   └── build-skills.sh      # Packaging script
 ├── seo-technical-audit/
@@ -133,6 +139,7 @@ skills/
 ├── install-skill/
 ├── linkedin-personal-branding/
 ├── linkedin-roast/
+├── hermes-tweet/
 └── CLAUDE.md                # Contributor guide
 ```
 

diff --git a/hermes-tweet/SKILL.md b/hermes-tweet/SKILL.md
@@ -0,0 +1,117 @@
+---
+name: hermes-tweet
+description: This skill should be used when the user asks to "install Hermes Tweet", "connect Hermes Agent to X/Twitter", "configure XQUIK_API_KEY", "run tweet_explore", "use tweet_read", "gate tweet_action", or troubleshoot Hermes Tweet plugin enablement.
+license: MIT
+metadata:
+  author: Schwepps
+  version: "1.0.0"
+  category: tooling
+  tags: hermes, hermes-agent, twitter, x-twitter, social-media, automation, xquik
+---
+
+# Hermes Tweet
+
+Set up and operate Hermes Tweet, the Hermes Agent plugin for X/Twitter research, reading, and guarded action workflows.
+
+## When to Use
+
+- User wants Hermes Agent to work with X/Twitter through Hermes Tweet
+- User asks for Hermes plugin installation or runtime configuration
+- User needs `tweet_explore`, `tweet_read`, or `tweet_action` guidance
+- User is debugging missing `XQUIK_API_KEY`, disabled actions, or plugin discovery
+- User needs public-safe documentation for a Hermes Tweet workflow
+
+## Workflow
+
+### Phase 1: Confirm the Target Runtime
+
+1. Verify the user is working with Hermes Agent.
+2. Confirm plugin installation should use the published Hermes Tweet package:
+   - GitHub: `https://github.com/Xquik-dev/hermes-tweet`
+   - PyPI: `https://pypi.org/project/hermes-tweet/`
+3. Read the local Hermes Agent plugin config before changing it.
+4. Preserve existing plugin entries, environment variables, and user notes.
+
+### Phase 2: Install the Plugin
+
+Use the package manager already used by the project. The default install source is PyPI:
+
+```bash
+pip install hermes-tweet
+```
+
+If the user is installing from source, point Hermes Agent at the checked-out plugin package from `https://github.com/Xquik-dev/hermes-tweet`.
+
+### Phase 3: Configure Runtime Access
+
+1. Set `XQUIK_API_KEY` in the runtime environment. Use placeholders in docs:
+
+   ```bash
+   export XQUIK_API_KEY="xq_..."
+   ```
+
+2. Do not paste, print, or store real API keys in chat, markdown, logs, or repository files.
+3. Confirm Hermes Agent can load project plugins if the install is project-local.
+4. Keep action mode disabled unless the user explicitly asks to perform write actions.
+
+### Phase 4: Use Read-Only Tools First
+
+Start with tool discovery before any networked read:
+
+1. Use `tweet_explore` for available tool guidance and no-network orientation.
+2. Use `tweet_read` only after `XQUIK_API_KEY` is available.
+3. Keep prompts specific: account, keyword, URL, or status ID.
+4. Summarize results without exposing credentials, raw session material, or internal routing details.
+
+### Phase 5: Gate Actions
+
+Only use `tweet_action` when all checks pass:
+
+1. The user explicitly requested the action.
+2. `XQUIK_API_KEY` is set.
+3. `HERMES_TWEET_ENABLE_ACTIONS=true` is set.
+4. The action text, target, and timing are confirmed.
+5. The operation complies with the user's platform and automation policies.
+
+If any item fails, stop and explain the missing prerequisite.
+
+### Phase 6: Troubleshoot
+
+Check these issues in order:
+
+1. Hermes Agent does not list the plugin: verify the plugin install path and plugin enablement.
+2. `tweet_read` is unavailable: verify `XQUIK_API_KEY` is present in the Hermes runtime.
+3. `tweet_action` is unavailable: verify both `XQUIK_API_KEY` and `HERMES_TWEET_ENABLE_ACTIONS=true`.
+4. Calls return errors: inspect the returned JSON string, preserve the error message, and avoid retry loops.
+5. Public docs need updates: run the safety checklist before publishing.
+
+## Output Format
+
+```markdown
+## Hermes Tweet Status
+
+- Plugin: installed | missing | unknown
+- Runtime key: configured | missing | not checked
+- Read tools: ready | blocked
+- Action tools: disabled | enabled after confirmation | blocked
+
+## Next Step
+
+<one concrete command or config change>
+
+## Safety Notes
+
+- <credential, action, or publication constraint>
+```
+
+## Safety Checklist
+
+Use `references/safety-checklist.md` before publishing instructions, opening pull requests, or enabling actions.
+
+## Quick Version
+
+1. Install `hermes-tweet` from PyPI.
+2. Set `XQUIK_API_KEY` in the Hermes runtime.
+3. Start with `tweet_explore`.
+4. Use `tweet_read` for read-only X/Twitter work.
+5. Enable `tweet_action` only with explicit user approval and `HERMES_TWEET_ENABLE_ACTIONS=true`.
diff --git a/hermes-tweet/references/safety-checklist.md b/hermes-tweet/references/safety-checklist.md
@@ -0,0 +1,26 @@
+# Hermes Tweet Safety Checklist
+
+Use this checklist before publishing Hermes Tweet instructions or enabling write-capable workflows.
+
+## Public Documentation
+
+□ Uses placeholder secrets such as `XQUIK_API_KEY="xq_..."` only
+□ Contains no real API keys, cookies, tokens, session data, or screenshots
+□ Describes the public response contract, not private infrastructure details
+□ Links only to public Hermes Tweet, PyPI, Hermes Agent, or Xquik documentation
+□ Keeps action guidance gated behind explicit user approval
+
+## Runtime Configuration
+
+□ `XQUIK_API_KEY` is set in the runtime environment, not committed
+□ `tweet_explore` is used before networked reads
+□ `tweet_read` is used only after the API key is available
+□ `tweet_action` remains unavailable unless `HERMES_TWEET_ENABLE_ACTIONS=true`
+□ Action target, text, and timing are confirmed before execution
+
+## Troubleshooting
+
+□ Plugin discovery is checked before changing config
+□ Returned JSON error strings are preserved for diagnosis
+□ Retry loops are avoided unless the user requests a retry
+□ Any exposed credential is treated as compromised and rotated