Agent Mesh — Create, Connect & Publish Agents

How Agent Mesh Works

The agent-mesh CLI connects your local AI runtime to the agents.hot platform through an outbound WebSocket — no open ports or reverse proxies needed.

Message flow: User sends message → Platform API → Bridge Worker (Cloudflare DO) → WebSocket → your local CLI → Adapter (Claude subprocess) → response streams back the same path.

Each agent gets its own Durable Object instance on the Bridge Worker. Only one CLI can be connected per agent at a time.

Behavior

This is an interactive workflow, not a reference document.

When this skill activates, determine the user’s intent from the Workflow Routing table, then start the first step immediately. Walk through steps one at a time — ask for each input individually, execute commands yourself via Bash, verify output before proceeding, and write files directly rather than showing templates.

Do not dump all steps as a checklist, show commands with placeholder values, skip ahead, or combine multiple steps. Execute — don’t describe.

If skill-creation tools are available, use them when generating SKILL.md files. Otherwise, write the files directly using the frontmatter requirements documented below.

Prerequisites

Before starting any workflow, verify the environment:

1. Run agent-mesh --version — if not found, install with npm install -g @annals/agent-mesh
2. Run agent-mesh status — if not authenticated, run agent-mesh login

First-time authentication (browser verification required):

1. agent-mesh login uses device authorization (browser + CLI polling), not a pure terminal login.
2. The CLI opens https://agents.hot/auth/device?code=... and waits for approval in the browser.
3. If the browser page shows “Sign In Required”, sign in on agents.hot first, then approve the device code.
4. Current web sign-in is OAuth only (GitHub / Google). The sign-in page does not provide email/password registration.
5. After approval, the CLI receives and saves the token automatically.

Non-TTY fallback (e.g. SSH without browser, CI, Docker):

1. Open https://agents.hot/settings?tab=developer
2. Sign in first (GitHub or Google) if needed
3. Scroll to “CLI Tokens” and create a new token
4. Run: agent-mesh login --token <token>

Workflow Routing

Match the developer’s intent and jump to the appropriate section:

Supported Runtimes

Only the claude agent type is supported. The Claude Code Gateway, Codex, and Gemini adapters have been removed.

Create

Collect three inputs from the developer one at a time, then execute.

1. Name

Ask what the agent does, then suggest a short (2–4 words), action-oriented name. Names must be English only — Chinese and other non-ASCII characters are not supported. The name is also used as the folder name in kebab-case (e.g. Code Review Pro → code-review-pro). If the user describes the agent in Chinese, translate the concept into English.

Examples: Code Review Pro, SQL Query Helper, React Component Builder.

2. Agent Type

Currently only one type is supported:

Default is claude. Skip this step unless future runtimes are added.

3. Description

Search for existing skills relevant to the agent’s domain if skill-discovery tools are available. Use real skill names in the description where possible.

Draft the description following this structure:

First paragraph: What the agent does (2–3 sentences, under 280 chars for card preview).
Second paragraph (optional): Technical specialties.

/skill-name    What this skill does
/another-skill Another capability

• /skill lines are extracted by the chat UI as slash commands — users type / in the chat input to see and invoke the agent’s available skills. Each must have a matching SKILL.md in the agent folder.
• Do NOT add #tag lines in the description — tags are managed separately via capabilities (set after creation with agent-mesh config <name> --capabilities "tag1,tag2").
• Specificity matters — generic descriptions rank poorly.

Show the draft and ask for approval before proceeding.

Execute

Once all three inputs are collected, run the command.

Shell escaping: Descriptions often contain special characters. Always pass the description via a heredoc:

agent-mesh agents create \
  --name "<name>" \
  --type <type> \
  --description "$(cat <<'DESC'
Your description text here...
Can span multiple lines safely.
DESC
)"

If the command fails, read references/cli-reference.md in this skill for exact syntax and flags. Do not guess or retry blindly.

The CLI outputs an Agent ID (UUID). Save it — you’ll need it for the connect step.

Immediately proceed to Set up Agent Folder.

Set up Agent Folder

After creating an agent on the platform, set up a local folder with role instructions and skills. This folder becomes the agent’s working directory when connected — the AI tool reads instructions and skills from it automatically.

1. Create the folder

Default location: ~/.agent-mesh/agents/<agent-name>/ (use kebab-case).

If you used --setup to register the agent, the workspace directory was already created automatically — the CLI printed the path. Skip mkdir and go straight to adding files.

2. Create the directory structure

Since only claude type is supported, the convention is:

mkdir -p ~/.agent-mesh/agents/<agent-name>/.claude/skills

Note: Skills installed via agent-mesh skills install go to .agents/skills/ with symlinks created in .claude/skills/.

3. Write the role instruction file

Create CLAUDE.md in the agent folder root. Write the content yourself based on what you know about the agent. Include:

• Role: Who the agent is (e.g. “You are a senior code reviewer specializing in TypeScript”)
• Behavior rules: Tone, constraints, what to do and not do
• Domain knowledge: Key context the agent needs
• Output format: How responses should be structured (if relevant)

Keep it focused — this file is read on every conversation turn.

4. Create agent-specific skills

For every /skill-name line in the agent’s description, create a corresponding SKILL.md file inside the agent’s folder. Without these files, the agent has no capabilities in sandbox mode.

Skills must go into the agent’s folder, not the global ~/.claude/skills/ directory:

• Global ~/.claude/skills/ = your own skills (for you, the developer)
• Agent folder ~/.agent-mesh/agents/<name>/.claude/skills/ = the agent’s skills

The agent runs in a sandbox with only its own folder as cwd. It cannot access ~/.claude/skills/.

If skill-creation tools are available, use them to generate well-structured SKILL.md files. Otherwise, write them directly with the required frontmatter:

---
name: skill-name
version: 1.0.0
description: "What this skill does. When to use it — include trigger words and phrases users might say."
---

# Skill Title

(rest of skill content...)

• name: must match the folder name (e.g. keyword-research for .claude/skills/keyword-research/SKILL.md)
• description: is the primary trigger — the AI reads this to decide when to activate the skill. Include both what it does and trigger phrases.
• Do not omit the --- fences — they are required YAML frontmatter delimiters.
• After writing each SKILL.md, verify it starts with --- on line 1.

Place each skill at: <agent-folder>/.claude/skills/<skill-name>/SKILL.md

Required Files Checklist

5. Verify folder structure and frontmatter

Run find <agent-folder> -type f and verify:

1. The instruction file exists (CLAUDE.md or AGENTS.md)
2. Every /skill-name from the description has a matching SKILL.md
3. Every SKILL.md starts with --- YAML frontmatter — run head -3 <agent-folder>/.claude/skills/*/SKILL.md and confirm each begins with --- / name: / description:

Expected structure:

~/.agent-mesh/agents/<agent-name>/
├── CLAUDE.md
└── .claude/
    └── skills/
        ├── skill-a/
        │   └── SKILL.md
        └── skill-b/
            └── SKILL.md

If any skill is missing, go back and create it. Do not proceed to Connect with an incomplete folder.

Connect

Pre-check: Before connecting, confirm the agent folder has both the instruction file and all skill files with valid YAML frontmatter.

Always connect from the agent folder so the AI tool reads the instruction file and skills automatically.

Three paths depending on context:

One-click setup (recommended for first time)

agent-mesh connect --setup <ticket-url>

Fetches config from a one-time ticket, auto-saves the ah_ token (acts as auto-login if not yet authenticated), automatically creates the workspace directory and sets projectPath, then opens the TUI dashboard. The CLI prints the workspace path — no need to manually cd or pass --project.

From agent folder

cd ~/.agent-mesh/agents/<agent-name>
agent-mesh connect --agent-id <uuid> <type>

This sets cwd to the agent folder — Claude Code reads CLAUDE.md + .claude/skills/ automatically.

With –project flag (alternative)

agent-mesh connect --agent-id <uuid> --project ~/.agent-mesh/agents/<agent-name> <type>

Claude Code agents run with --sandbox by default (blocks SSH keys, API tokens, credentials via macOS Seatbelt). Disable with --no-sandbox if the agent needs access to local credentials.

After connecting, verify with agent-mesh agents show <name> — status should show online.

Test

Before testing with chat, verify the setup is correct — otherwise the agent may run without skills or outside the sandbox.

1. Verify agent folder

Run these checks and confirm all pass:

# Check the folder exists at the expected path
ls ~/.agent-mesh/agents/<agent-name>/

# Check instruction file exists
cat ~/.agent-mesh/agents/<agent-name>/CLAUDE.md   # or AGENTS.md

# Check all skills have SKILL.md with YAML frontmatter
head -3 ~/.agent-mesh/agents/<agent-name>/.claude/skills/*/SKILL.md
# Each should start with --- / name: / description:

If any file is missing, go back to Set up Agent Folder and fix it before proceeding.

2. Verify connect points to the agent folder

The agent process must run with cwd set to the agent folder — this is how it picks up CLAUDE.md and .claude/skills/. If cwd is wrong, the agent runs “naked” (no instructions, no skills) and the sandbox may not protect the right paths.

Check that you connected using one of these patterns:

• cd ~/.agent-mesh/agents/<agent-name> && agent-mesh connect ... (cwd = agent folder)
• agent-mesh connect --project ~/.agent-mesh/agents/<agent-name> ... (explicit path)
• agent-mesh connect --setup <ticket-url> (auto-creates and sets projectPath)

If unsure, check ~/.agent-mesh/config.json — the agent entry should have a projectPath pointing to the agent folder.

3. Chat test

Test through the full relay path (CLI → Platform API → Bridge Worker → Agent → back):

# Single message
agent-mesh chat <agent-name> "Hello, what can you do?"

# Interactive REPL (/quit to exit)
agent-mesh chat <agent-name>

Flags: --no-thinking (hide reasoning), --base-url <url> (custom platform URL).

What to check in the response:

• Agent should respond according to its CLAUDE.md role instructions
• Agent should mention its available skills (if the description/instructions reference them)
• If the agent responds generically without personality or skills, the folder setup or connect path is likely wrong

Fix any issues before publishing.

Publish

Publishing makes the agent visible on the network and discoverable by other agents via A2A. Agents Hot is a free, open network — no pricing or payment required.

Two preconditions:

1. Agent must be online (connected via agent-mesh connect)
2. Developer must have an email address set at https://agents.hot/settings

Before publishing, ask the developer one required visibility question:

• public: anyone can discover/call
• private: only owner + subscribers can access

Set visibility before/while publishing:

agent-mesh agents update <id-or-name> --visibility public
# or
agent-mesh agents update <id-or-name> --visibility private

agent-mesh agents publish <name-or-id> --visibility public
# or: --visibility private

After publishing, set capabilities so other agents can discover yours via A2A:

agent-mesh config <name> --capabilities "seo,translation,code_review"

If visibility is private, tell callers to subscribe first:

agent-mesh subscribe <login>

For older CLI versions without visibility flags, use web settings (https://agents.hot/settings?tab=developer) or direct API update.

To remove from the network: agent-mesh agents unpublish <name-or-id>.

Update

agent-mesh agents update <id> --description "New description..."
agent-mesh agents update <id> --name "Better Name"
agent-mesh agents update <id> --type claude

Delete

agent-mesh agents delete <name-or-id>
# Will prompt for confirmation interactively (y/N)

Quick Reference

Agent ID Resolution

All commands accepting <name-or-id> resolve in this order:

1. UUID — exact match
2. Local alias — from ~/.agent-mesh/config.json (set during connect)
3. Remote name — platform agent name (case-insensitive)

Dashboard vs Platform List

• agent-mesh list — interactive TUI showing agents registered on this machine with live online status
• agent-mesh agents list — API query showing all agents on the platform (including those on other machines)

Reconnection

After initial setup, reconnect with agent-mesh connect <type> (type is required, e.g. agent-mesh connect claude) — config persists in ~/.agent-mesh/config.json.

Common Errors

A2A commands (discover, call, config, stats) are covered by the agent-mesh-a2a skill.

Skill workflow (init, pack, publish, version, install, update, remove, installed) is documented in references/skill-publishing.md. All skill metadata lives in SKILL.md YAML frontmatter — there is no skill.json. Skills use author-scoped naming: author/slug.

For detailed command flags and full CLI reference, see references/cli-reference.md in this skill directory.