Guide Infrastructure

Shared Tools Infrastructure

When you have multiple AI agents (Claude Code, Cursor, custom agents), keep tool documentation in sync with a shared infrastructure.

# the_problem

Without shared infrastructure, you end up with:

  • ✗ Duplicate documentation across agents
  • ✗ Inconsistent tool names and usage
  • ✗ Forgetting to update all agents when tools change
  • ✗ Agents not knowing about available tools

# the_solution

Single source of truth with automatic syncing: 

~/.config/agents/
├── TOOLS-SHARED.md    # Single source of truth
├── MEMORY.md          # Shared memory
├── sync-tools.sh      # Sync script
└── agents.json        # Agent configurations

Sync to:
├── ~/.claude/TOOLS-SHARED.md
├── ~/.cursor/TOOLS-SHARED.md
└── ~/agents/kit/TOOLS-SHARED.md

# tools_shared_md

Document all your tools in one place: 

# TOOLS-SHARED.md — Shared across all agents
# Edit this file, run sync-tools.sh, all agents get the update.
# KEEP UNDER 18KB — one-liner per tool, point to help for details.

> **🔧 CLI tools — build, fix, extend (MANDATORY):** Never write
> one-off scripts or raw API calls when a kit tool could do the job.
> **Create new kit commands** for repeatable tasks.
> **Fix broken tools immediately.** **Extend existing tools** when
> a flag or subcommand is missing. Verify, then use the tool.

---

## 📧 Email & Communication

kit email <command> [account]  — Gmail management
  inbox-scan, read, search, send, reply, draft, archive, labels
  Accounts: personal | work. Default to drafts, not sends.

kit cal <command> [account]   — Google Calendar
  events, today, create, update, search, freebusy

kit slack <command>           — Slack messaging
  dm, group-dm, read-channel, channels, users

kit shortlink <url>           — is.gd URL shortener

## 🐦 Social Media

kit tweet "text"              — Post to Twitter/X
kit reply <id> "text"         — Reply to tweet
kit thread "t1" "t2" ...     — Post thread
kit yt <command>              — YouTube (upload, playlists, analytics)
kit fb <command>              — Facebook page management

## 🛒 E-Commerce

kit shop <command>            — Shopify (products, orders, inventory)
kit amazon <command>          — Amazon SP-API
kit shipstation <command>     — ShipStation shipping
kit zendesk <command>         — Support tickets

## 🔧 Utilities

kit screenshot <url>          — Playwright screenshots
kit video-analyze <file> "p"  — Gemini video analysis
kit oura <command>            — Oura Ring health data
kit cf <command>              — Cloudflare DNS/cache

## 📖 Documentation

docs.sh list                  — List all docs
docs.sh search <query>        — Search across docs
docs.sh read <slug>           — Read a doc
docs.sh refresh               — Reload after editing

## Quick Reference
- Email: \`kit email inbox-scan personal\`
- Calendar: \`kit cal today\`
- URLs: \`kit shortlink https://example.com\`

# sync_script

Automate syncing to all agent configurations: 

#!/bin/bash
# sync-tools.sh - Sync TOOLS-SHARED.md to all agent configs

SOURCE="$HOME/.config/agents/TOOLS-SHARED.md"
TARGETS=(
  "$HOME/.claude/TOOLS-SHARED.md"
  "$HOME/.cursor/TOOLS-SHARED.md"
  "$HOME/agents/kit/TOOLS-SHARED.md"
)

for target in "${TARGETS[@]}"; do
  cp "$SOURCE" "$target"
  echo "Synced to $target"
done

echo "Tools documentation synced to all agents"

Automation Options

  • • Run manually: ./sync-tools.sh
  • • Git hook: Sync on commit
  • • Cron job: Sync every hour
  • • File watcher: Sync on change

# agent_integration

Reference the shared file in each agent's config:

Claude Code (~/.claude/CLAUDE.md)

# ~/.claude/CLAUDE.md

## Shared Tools
The following tools are available across all sessions.
See TOOLS-SHARED.md for full documentation.

@TOOLS-SHARED.md

## Quick Reference
- Email: `kit email inbox-scan personal`
- Calendar: `kit cal today`
- URLs: `curl is.gd/create.php?format=simple&url=...`

The @TOOLS-SHARED.md reference tells Claude Code to include that file's contents.

# openclaw_setup

For OpenClaw or custom agent frameworks, configure context files: 

# agents.json - OpenClaw agent configuration
{
  "agents": {
    "kit": {
      "name": "Kit",
      "description": "Personal assistant agent",
      "tools": ["email", "calendar", "drive", "shortlink"],
      "context_files": [
        "~/.config/agents/TOOLS-SHARED.md",
        "~/.config/agents/MEMORY.md"
      ]
    },
    "dev": {
      "name": "Dev Assistant",
      "description": "Development helper",
      "tools": ["git", "npm", "docker"],
      "context_files": [
        "~/.config/agents/TOOLS-SHARED.md",
        "./CLAUDE.md"
      ]
    }
  }
}

# best_practices

Single Source of Truth

Only edit TOOLS-SHARED.md in one place, then sync

Version Control

Keep your agent configs in a git repo for history

Document Tool Changes

Update TOOLS-SHARED.md whenever you add or modify tools

Include Examples

Show actual command examples, not just syntax

Keep It Under ~18KB

This file is loaded into every agent's context window on every conversation. If it's too large, it wastes tokens and slows responses. Use one-liner descriptions and point to kit <tool> help for details — don't expand full documentation inline.

Separate Public from Private

Don't include internal API tools in public documentation

# recommended_structure

A complete agent infrastructure setup: 

~/.config/agents/
├── TOOLS-SHARED.md      # All tool documentation
├── TOOLS-INTERNAL.md    # Internal-only tools (not synced)
├── MEMORY.md            # Shared context/memory
├── agents.json          # Agent configurations
├── sync-tools.sh        # Sync script
└── templates/
    ├── CLAUDE.md        # Template for new projects
    └── MEMORY.md        # Template for new projects

~/.claude/
├── CLAUDE.md            # Global Claude Code config
├── TOOLS-SHARED.md      # ← Synced from source
└── MEMORY.md            # ← Synced or local

~/projects/my-app/
├── CLAUDE.md            # Project-specific
├── MEMORY.md            # Project-specific
└── ... (project files)