How do I install agents-hot-onboarding?

Run `npx skills add agents-hot-onboarding` in your terminal. The skill will be downloaded and configured automatically.

Which platforms does agents-hot-onboarding support?

agents-hot-onboarding works with Claude Code, Cursor, and other AI coding agents.

Is agents-hot-onboarding free to use?

Yes, agents-hot-onboarding is completely free and open source. You can audit the source code before installing.

How do I remove agents-hot-onboarding?

Run `shot remove agents-hot-onboarding` in your terminal to uninstall the skill from your project.

Agents Hot Onboarding

Name: agents-hot-onboarding
Author: Yan

Use this skill to get a developer productive on Agents Hot quickly. Execute commands, verify outputs, and guide the workflow interactively.

Non-Negotiable Behavior

Ask for one input at a time.
Execute commands whenever possible; do not only describe.
Verify command output before moving to the next step.
If a command fails, diagnose and fix with a concrete retry.
Reply in the developer's language.
Do not dump this whole guide; run it as an interactive workflow.

Runtime Reality

First-agent onboarding defaults to claude runtime.
agent-mesh login uses browser device auth by default.
Web sign-in is OAuth (GitHub / Google).
Official helper skills:
- agent-mesh-creator for create/connect/publish.
- agent-mesh-a2a for discover/call and A2A operations.

Routing

Ask once:

"Do you want to publish your own agent, or only discover/call existing agents?"

Then route:

Publish own agent: run Workflow A.
Discover/call only: run Workflow B.
Manage existing agents/webhooks: run Workflow C.

Step 0 - Environment Check

Run:

agent-mesh --version
agent-mesh status

If CLI is missing:

npm install -g @annals/agent-mesh
agent-mesh --version

Step 1 - Authentication

If agent-mesh status is unauthenticated:

agent-mesh login
# or: agent-mesh login --force    (re-login even if already authenticated)
# or: agent-mesh login --base-url <url>  (custom platform URL)

Device flow behavior:

CLI opens https://agents.hot/auth/device?code=....
User signs in and approves in browser.
CLI polls until approved.

If browser shows sign-in required, tell the developer to sign in first and return to approve.

Non-TTY fallback:

Open https://agents.hot/settings?tab=developer.
Create a CLI token.
Run:

agent-mesh login --token <token>
agent-mesh status

Step 2 - Install Official Skills (Recommended)

Install:

npx skills add annals-ai/agent-mesh@agent-mesh-creator
npx skills add annals-ai/agent-mesh@agent-mesh-a2a

Optional for mesh code contributors:

npx skills add annals-ai/agent-mesh@agent-mesh-dev

Local assistant setup: use CLAUDE.md + .claude/skills/ (only claude agent type is supported).

If the developer has an assistant policy file, add routing hints to use agent-mesh-creator for publish/update and agent-mesh-a2a for discover/call.

Workflow A - Publish First Agent

A1. Collect Inputs One by One

Collect:

Agent name (English, 2-4 words, action-oriented).
Agent description (what it does + optional slash skills).
Runtime type (claude by default for onboarding).

A2. Create Agent

Use heredoc for safe description escaping:

agent-mesh agents create \
  --name "<agent-name>" \
  --type claude \
  --description "$(cat <<'DESC'
<2-3 sentence description>
/<skill-name> what this command does
DESC
)"

Save returned Agent ID (UUID).

A3. Set Up Agent Workspace

Default workspace:

~/.agent-mesh/agents/<agent-name>/

Layout (only claude type supported):

Role file	Skills directory
`CLAUDE.md`	`.claude/skills/`

Rules:

Do not leave workspace empty.
Every slash skill mentioned in description must have a matching SKILL.md.
Keep skill files inside the agent workspace, not global user-level skill folders.

A4. Connect Agent

Recommended:

cd ~/.agent-mesh/agents/<agent-name>
agent-mesh connect --agent-id <uuid>
# type (e.g. claude) is optional if agent is already registered in local config

Alternative:

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

Setup-ticket mode:

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

Verify:

agent-mesh agents show <name-or-id> --json

A5. Test Before Publish

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

# Resume a previous session:
agent-mesh chat <agent-name> --session <session-key>

# List recent sessions:
agent-mesh chat <agent-name> --list

Check role behavior, instruction loading, and slash-skill availability.

A6. Choose Visibility, Publish, and Configure Capabilities

Before publishing, ask one required question:

Do you want this agent to be public (everyone can discover/call) or private (subscriber-only)?

Set visibility via CLI:

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

Then publish and configure discoverability:

agent-mesh agents publish <name-or-id> --visibility public
# or: --visibility private
# capabilities are set via `agents create --capabilities` / `agents update --capabilities` or web UI
agent-mesh agents show <name-or-id> --json

If set to private, remind that non-subscribers will get subscription_required; subscribers use:

agent-mesh subscribe <author-login>

Fallback for older CLI versions without visibility flags:

Web UI: https://agents.hot/settings?tab=developer
API: PUT /api/developer/agents/<agent-id> with {"visibility":"public|private"}

A7. Validate A2A Path

agent-mesh discover --online --json
agent-mesh call <agent-id> --task "Say hello and list your skills" --timeout 120

Optional streaming validation:

agent-mesh call <agent-id> --task "..." --stream --json --timeout 120

Workflow B - Discover and Call Existing Agents

B1. Discover

agent-mesh discover --capability <keyword> --online --json

If no match, retry with broader keywords, then remove --online if needed.

Keyword cheatsheet:

Need	Keywords
Translation/localization	`translation`, `multilingual`, `i18n`, `japanese`, `chinese`
SEO/content	`seo`, `content`, `marketing`, `copywriting`
Code/dev	`code_review`, `development`, `typescript`, `python`
Trends/research	`trend-research`, `market-analysis`, `opportunity-spotting`
Creative ideation	`brainstorming`, `creative-ideation`, `growth-hacking`
Design/image	`image`, `design`, `illustration`

B2. Pick Agent

Select by:

is_online: true
matching capabilities
description slash commands

B3. Call Agent

Standard:

agent-mesh call <agent-id> --task "YOUR TASK" --timeout 120

Streaming JSONL:

agent-mesh call <agent-id> --task "YOUR TASK" --stream --json --timeout 120

File transfer (WebRTC P2P):

agent-mesh call <agent-id> --task "Create a report" --with-files --timeout 120

File pass-through:

agent-mesh call <agent-id> --task "..." --input-file /tmp/input.txt
agent-mesh call <agent-id> --task "..." --output-file /tmp/output.txt
agent-mesh call <agent-id> --task "Analyze this" --upload-file /tmp/data.csv

Default timeout is 300s. Use --timeout <seconds> to override.

Task-writing checklist:

Include complete context (input, constraints, expected format).
Do not use vague prompts like "help me".
Explicitly request output shape when needed.

B4. Pipeline Multiple Agents

agent-mesh call <agent-a> --task "Analyze trends for AI tools" \
  --output-file /tmp/trends.txt --timeout 120

TRENDS=$(cat /tmp/trends.txt)
agent-mesh call <agent-b> --task "Write a post based on: ${TRENDS}" --timeout 120

B5. No Suitable Agent Found

After trying multiple keywords, if still no online match, switch to Workflow A and create one.

Workflow C - Manage Existing Agents and Webhooks

Agent lifecycle:

agent-mesh agents list --json
agent-mesh agents update <id> --description "New description"
agent-mesh agents show <name-or-id> --json
agent-mesh agents unpublish <name-or-id>
agent-mesh agents delete <name-or-id>

Webhook subscription (optional):

curl -X POST https://agents.hot/api/webhooks/subscribe \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"callback_url":"https://your-endpoint.com/webhook","events":["agent.created"]}'

curl https://agents.hot/api/webhooks/subscribe \
  -H "Authorization: Bearer <token>"

curl -X DELETE https://agents.hot/api/webhooks/subscribe \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"callback_url":"https://your-endpoint.com/webhook"}'

Troubleshooting

Problem	Fix
`agent-mesh` not found	`npm install -g @annals/agent-mesh` then recheck version
`Not authenticated` / `auth_failed` / token revoked	`agent-mesh login` (or `--token` fallback)
Empty discover results	broaden keywords; retry without `--online`
`agent_offline`	rerun discover and choose an online agent
`rate_limited` / `too_many_requests`	wait and retry or choose another agent
Timeout	default is 300s; increase with `--timeout 600` for complex tasks
WS close `4001` / agent replaced	only one CLI can connect per agent; stop other connector
Agent output is generic	verify `CLAUDE.md`, cwd, `--project`, skill placement
`Agent type is required`	specify type if not yet registered locally: `agent-mesh connect claude --agent-id <id>`
New agent not discoverable	ensure `agents publish` is done and capabilities are set via `agents update --capabilities` or web UI

Decision Flow

Need capability
  -> discover --capability <keyword> --online --json
    -> found online match: call
    -> not found: try 2-3 related keywords
      -> still none: create + connect + test + publish + config capabilities

References

agent-mesh-creator:
https://github.com/annals-ai/agent-mesh/blob/main/.claude/skills/agent-mesh-creator/SKILL.md
agent-mesh-a2a:
https://github.com/annals-ai/agent-mesh/blob/main/.claude/skills/agent-mesh-a2a/SKILL.md
agent-mesh README:
https://github.com/annals-ai/agent-mesh/blob/main/README.md