commit a77e1c3efbf82081e71b44db26ada3bb854fdb68 Author: BarnacleBoy Date: Fri May 8 15:49:35 2026 +0000 Initial release: sender/recipient agnostic transfer-pack skill diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..2649616 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Jezza Hehn + +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. \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..306d9b9 --- /dev/null +++ b/README.md @@ -0,0 +1,51 @@ +# transfer-pack + +A Hermes Agent skill for sending transfer packets (files + instructions) between remote agent instances withDiscord notification. + +## What It Does + +When you need to send files or instructions to another Hermes Agent running on a different machine, this skill: + +1. Packages files + a LETTER.md into a tarball +2. SCPs it to the recipient's server +3. Creates a one-shot cron job that notifies the recipient via Discord +4. Cleans up temp files + +## Installationsymlink: + +```bash +ln -s /path/to/transfer-pack ~/.hermes/skills/transfer-pack +``` + +Or copy the `SKILL.md` to `~/.hermes/skills/transfer-pack/SKILL.md`. + +## Usage + +From another skill or directly: + +``` +User: "Use transfer-pack to send the new config to CeeLo" +``` + +The skill will: +1. Parse AGENTS.md to find CeeLo's SSH address +2. Create a transfer packet with the files +3. Deliver to CeeLo's server +4. Schedule a Discord notification for CeeLo + +## Requirements + +- SSH key access to recipient servers +- `mcp_ssh` tool (SSH-MCP integration) +- Hermes cron support on both sender and recipient + +## Integration with agent-coordination + +This skill is designed to work with the [agent-coordination](https://git.jezzahehn.com/KrustyPlanet/agent-coordination) repository: + +- Parses `AGENTS.md` to resolve recipient names to SSH addresses +- Uses `PERSONALITY.md` for shared behavioral context (optional) + +## License + +MIT \ No newline at end of file diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..01a0a8d --- /dev/null +++ b/SKILL.md @@ -0,0 +1,156 @@ +--- +name: transfer-pack +description: "Send a transfer packet to a remote Hermes agent with file delivery and Discord notification." +version: 1.1.0 +metadata: + hermes: + tags: [transfer, agent-communication, scp, cron] +--- + +# Transfer Pack + +Send a transfer packet (files + letter) to a remote Hermes Agent instance. The recipient agent reads the letter and responds via Discord. + +## Prerequisites + +- SSH key access to recipient agent's server +- `mcp_ssh` tool available (SSH-MCP) +- Both agents must have Hermes cron support + +## Configuration + +Before using, identify from context or AGENTS.md: + +| Variable | Source | +|----------|--------| +| SENDER_NAME | Your agent name (e.g., BarnacleBoy, Lucy, CeeLo, MermaidMan) | +| RECIPIENT_NAME | Target agent name from AGENTS.md | +| RECIPIENT_SSH_HOST | Tailscale address from AGENTS.md | +| RECIPIENT_SSH_USER | SSH username for recipient server | +| USER_NAME | Human operator's name (for acknowledgment) | + +## Procedure + +### Step 1: Parse the prompt + +Identify: +- The **topic** (succinct kebab-case keyword from the user's prompt) +- The **files to include** (from context — code, docs, configs, etc.) +- The **instructions for the recipient** (what they should do with the contents) + +### Step 2: Create the transfer packet directory + +```bash +mkdir -p /tmp/transfer-packs/YYYY-MM-DD- +``` + +Use today's date and the succinct topic. Example: `2026-05-08-agent-coordination` + +### Step 3: Copy relevant files into the directory + +Copy all files referenced in the prompt into the packet directory. Use `cp` or `write_file` as appropriate. + +If no files needed, just create the LETTER.md. + +### Step 4: Write LETTER.md + +Write `LETTER.md` in the packet directory with this structure: + +```markdown +# Transfer Packet: + +**From:** (Hermes Agent) +**To:** (Hermes Agent) +**Date:** YYYY-MM-DD +**Topic:** + +--- + + +- What's in this packet +- Why it's being sent +- What the recipient should do with it +- Any specific instructions or context needed + +**At the end, include this line:** +"Please inform that this transfer was successful and include a brief summary of what you received." +``` + +The letter MUST end with the instruction to inform the user of success. + +### Step 5: Create the tarball + +```bash +cd /tmp/transfer-packs && tar czf YYYY-MM-DD-.tar.gz YYYY-MM-DD-/ +``` + +### Step 6: SCP the tarball to the recipient + +```bash +scp -o StrictHostKeyChecking=no /tmp/transfer-packs/YYYY-MM-DD-.tar.gz @:~/ +``` + +### Step 7: Extract the tarball on the recipient server + +Use SSH-MCP (`mcp_ssh_execute_command`): + +```bash +cd ~ && tar xzf YYYY-MM-DD-.tar.gz +``` + +### Step 8: Create a one-shot cron job on the recipient server + +Use SSH-MCP to run: + +```bash +hermes cron create \ + --name "transfer-ack-" \ + --deliver discord \ + --repeat 1 \ + 1m \ + "New transfer packet from . Please read ~/YYYY-MM-DD-/LETTER.md and follow the instructions inside." +``` + +This creates a one-shot cron job that: +- Runs in ~1 minute +- Triggers the recipient agent with the notification prompt +- Delivers the response to Discord +- Auto-removes after running once (`--repeat 1`) + +**Note:** The cron ticker runs at 60s intervals, so it may take 1-2 minutes for the job to fire. + +### Step 9: Confirm to user + +Report: +- Packet directory name +- Files included +- That the cron notification was created +- Expected delivery timeframe (~1-2 minutes) + +## Cleanup + +After confirming the transfer, clean up local temp files: + +```bash +rm -rf /tmp/transfer-packs/YYYY-MM-DD- /tmp/transfer-packs/YYYY-MM-DD-.tar.gz +``` + +The recipient should clean up their copy after reading the letter. + +## Pitfalls + +- **Do NOT use `hermes -z` or `hermes chat -q`** — those output to stdout only, not Discord. Always use the cron mechanism with `--deliver discord`. +- **Do NOT try to message the recipient's Discord bot directly** — Discord bots cannot see messages from other bots. +- **The `--repeat 1` flag is required** — without it, the job runs indefinitely. +- **Schedule format:** Use `1m` (relative offset), not `now`. The cron ticker picks it up on the next tick. +- **SCP requires SSH key auth** — ensure `~/.ssh/authorized_keys` is set up on the recipient server for the sending agent's key. +- **Files must be in the tarball** — don't assume the recipient has access to your filesystem. Copy everything into the packet directory. +- **Hardcoded names** — always derive SENDER_NAME, RECIPIENT_NAME, and USER_NAME from context or AGENTS.md, never hardcode them. + +## Integration with agent-coordination + +For agents using the `agent-coordination` repository: + +1. Parse `~/.hermes/agent-coordination/AGENTS.md` (or equivalent path) to resolve recipient names to SSH hosts and users +2. Use `~/.hermes/agent-coordination/PERSONALITY.md` for shared behavioral context +3. The sender's name should match their entry in AGENTS.md \ No newline at end of file