🎙️ ConvoZen Agent Skills

Drop-in skills that teach your AI coding agent to build, edit, test & ship ConvoZen WhatsApp / voice agents — from the editor you already use.

A skill is a folder of instructions (SKILL.md + reference/ + templates/) your agent reads on demand. Once installed, you just talk to your agent in plain language — "create a WhatsApp support bot", "add this API as a tool", "test the agent on my number" — and it drives the convozen CLI for you.

$ npx @convozen/convozen-skills install

Installing 10 ConvoZen skills (global: /home/you)
  + Claude Code /creating-agents
  + Claude Code /editing-agents
  + Claude Code /testing-agents
  + Codex       /managing-actions
  + Codex       /managing-knowledge-bases
  ...
Done.  ↻ Restart your agent to pick up the new skills.

⚡ Quick start

# 1 ─ Install the skills into every agent we detect on this machine
npx @convozen/convozen-skills install

# 2 ─ Install the ConvoZen CLI the skills drive
curl -fsSL https://cli-dev.convozen.ai/install.sh | sh

# 3 ─ Restart your agent, then just ask it to "create a ConvoZen agent"

Heads-up: the skills are the instructions; the convozen CLI is the engine. Install both.

Requirements: Node.js ≥ 18 (for npx), and one supported agent (Claude Code, Codex, Cursor, Gemini CLI, or any Agent-Skills-compatible tool). Nothing is installed globally — npx runs the installer on the fly and only copies skill folders into your agent's skills/ dir.

🤖 Per-agent install

The installer auto-detects which agents are present (it looks for ~/.claude, ~/.codex, … ) and copies the skills into each. To target one explicitly, pass --agent. Pick your tool below:

Claude Code

npx @convozen/convozen-skills install --agent claude

→ ~/.claude/skills/

Codex

npx @convozen/convozen-skills install --agent codex

→ ~/.codex/skills/

Cursor

npx @convozen/convozen-skills install --agent cursor

→ ~/.cursor/skills/

Gemini CLI

npx @convozen/convozen-skills install --agent gemini

→ ~/.gemini/skills/

📁 Any other agent (generic)

Any tool that honours the Agent Skills skills/<name>/SKILL.md layout. Falls back here automatically when no known agent is detected.

npx @convozen/convozen-skills install --agent agents

→ ~/.agents/skills/

Combine & scope — --agent is repeatable, and you can install per-project instead of globally:

# multiple agents at once
npx @convozen/convozen-skills install --agent claude --agent codex

# into the current project (./.claude/skills) instead of your home dir
npx @convozen/convozen-skills install --project

🔄 Restart your agent after installing so it discovers the new skills.

🔁 Updating

When a new version ships, grab the latest and overwrite in place:

npx @convozen/convozen-skills@latest update

The @latest tag forces npx to fetch the newest published version instead of a cached one; update overwrites existing skills. (Plain install skips skills that already exist — use update, or install --force, to refresh them.)

🧰 Commands

| Command | Alias | What it does | |---|---|---| | install | add | Copy skills into detected (or --agent-selected) agents | | update | upgrade | Re-install the latest, overwriting existing skills (install --force) | | list | ls | Show the bundled skills and every supported agent + its target dir | | help | -h, --help | Usage, options and examples |

Options

| Flag | Default | Meaning | |---|---|---| | --agent <name> | auto-detect | Target a specific agent — repeatable. One of claude, codex, cursor, gemini, agents | | --global | ✅ on | Install into your home dir (~) | | --project / --local | — | Install into the current project dir instead | | --force | — | Overwrite skills that already exist (implied by update) |

# see what's bundled and where each agent gets it
npx @convozen/convozen-skills list

# full usage
npx @convozen/convozen-skills help

🧩 Requires the ConvoZen CLI

These skills drive the convozen CLI — the binary that actually talks to the ConvoZen backend. Install it first:

curl -fsSL https://cli-dev.convozen.ai/install.sh | sh
convozen auth login

Keep it current with the built-in self-updater:

convozen update      # pulls the latest binary, checksum-verified, in place

📦 What's inside

Ten self-contained skills — each ships with its own reference/ and templates/:

| Skill | Teaches your agent to… | |---|---| | getting-started | Orient in ConvoZen, auth, pick org/project | | inspecting-agents | List and read existing agents | | creating-agents | Build a new WhatsApp / voice agent end-to-end | | editing-agents | Safely fork-and-edit a published agent | | testing-agents | Run and validate an agent | | managing-actions | Wire up and edit agent actions | | managing-knowledge-bases | Attach and manage knowledge bases | | authoring-prompts | Write effective agent prompts | | selecting-voices-handlers-and-listeners | Pick voices, handlers and listeners | | troubleshooting | Diagnose and fix common failures |