CatchClaw Agentar Manager

Source: This skill is from the CatchClaw skill repository.

An agentar is a distributable agent archive (ZIP) containing workspace files such as SOUL.md, skills, and other configuration. It can be installed as a new agent or used to overwrite an existing agent with a single command.

Trigger Conditions

• User asks to search / find / browse agentars
• User asks to install / download a specific agentar
• User asks to export / package an agent as an agentar
• User asks to rollback / undo / restore a previous agent workspace
• User mentions the keyword "agentar" or "catchclaw"
• User asks to search / install / list teams or "agenteam"
• User asks to install a team from the marketplace
• User asks to check team status or list installed teams

Important: Before performing any action, verify the bundled CLI works (see CLI Setup). Do not run search, install, export, rollback, or team commands until verification passes.

CLI Setup (mandatory — run before any command)

1. Locate: The CLI is at the same directory as this SKILL.md (e.g. ~/.agents/skills/catchclaw/agentar_cli.mjs).
2. Verify: Run node <skill-dir>/agentar_cli.mjs version. Only after it succeeds, proceed with search/install/export/rollback/team commands.

Never run $CLI search, $CLI install, $CLI export, $CLI rollback, or $CLI team … until verification passes.

CLI Location

The CLI is bundled in this skill's directory. Run it directly:

node <skill-dir>/agentar_cli.mjs <command>

Where <skill-dir> is the directory containing this SKILL.md (e.g. ~/.agents/skills/catchclaw/).

All commands below use $CLI as shorthand for node <skill-dir>/agentar_cli.mjs.

Environment Variables (optional)

These are listed in metadata.openclaw.requires.env for registry/security analysis. Neither is required for normal use; omit both to use defaults.

• AGENTAR_API_BASE_URL — Override the default API base URL (defaults to https://catchclaw.me)
• AGENTAR_HOME — Override the default CLI config directory (defaults to ~/.agentar)

Paths read or written by the bundled CLI

Aligned with metadata.openclaw.requires.config and metadata.json in this skill:

Critical: Install Command Selection

• Single agentar → $CLI install <slug> --name <name>
• Team (agenteam) → $CLI team install <slug>

NEVER use $CLI install for teams. It will fail because teams are not individual agentars. If the instruction mentions "team", "agenteam", or the slug contains "team", use $CLI team install.

If unsure, run $CLI search <slug> first — the result will show the type.

Commands

Search

$CLI search <keyword>

Search the CatchClaw marketplace for agentars matching the keyword.

Install

$CLI install <slug> --name <name> [--api-key <key>] [--version <ver>]
$CLI install <slug> --overwrite [--version <ver>]

Install an agentar from the marketplace.

Options:

• --name <name> — Create a new agent with the given name. Existing agents are not affected. (Preferred; list this option first when prompting.)
• --overwrite — Overwrite the main agent (~/.openclaw/workspace). Existing workspace is backed up automatically. Never use without the user's explicit selection.
• --api-key <key> — (Optional) API key to save into skills/.credentials for agentars that require backend authentication.
• --version <ver> — (Optional) Install a specific version. When omitted, installs the latest version.

Version conflict handling: When installing a specific version and the agent is already installed locally with a different version, the CLI will prompt:

"agent-name" (v1.0.0) is already installed. Install v1.4.0? [y/N]

• Answer y to backup the existing version and install the new one
• Answer N (or Enter) to abort
• Use --overwrite to skip the confirmation prompt
• If the existing installation has no version metadata, the prompt shows "(unknown version)"

Export

$CLI export [--agent <id>] [-o <path>] [--include-memory]

Export an agent as a distributable agentar ZIP package. MEMORY.md is excluded by default. Output defaults to ~/agentar-exports/. Sensitive files (.credentials, .env, .secret, .key, .pem) are automatically filtered out.

Options:

• --agent <id> — Agent ID to export. If the user did not specify an agent, you MUST list agents and ask the user to choose before running export; do not export without the user's selection.
• -o, --output <path> — Output ZIP file path.
• --include-memory — Include MEMORY.md in export (excluded by default).

Rollback

$CLI rollback
$CLI rollback --latest

Restore a workspace from backup. Without --latest, lists all available backups for selection. The current workspace is automatically backed up before restoring, so rollback is always safe.

Version

$CLI version

Show the CLI version.

Team Commands

Team Search

$CLI team search <keyword>

Search the CatchClaw marketplace for teams matching the keyword. Results include slug, name, version, and member count.

Team Install

$CLI team install <slug> [--version <ver>]

Install a team and all its member agents from the marketplace.

Options:

• --version <ver> — (Optional) Install a specific version of the team. When omitted, installs the latest version. The version is passed to the backend to fetch the corresponding team manifest snapshot with pinned member versions.

Behavior:

• Fetches the team manifest (name, members, collaboration type)
• Installs each member agent as a new agent (or reuses if already installed locally)
• Writes team registry to ~/.openclaw/agentar-teams/<slug>/team.yaml
• Updates each member's AGENTS.md with team coordination block

Member version conflict handling: When a team specifies particular versions for its member agents, and a member is already installed locally with a different version, the CLI will prompt per member:

"agent-a" (v1.0.0) is already installed. Team requires v1.2.0. Upgrade? [y/N]

• Answer y to upgrade that member agent (with automatic backup)
• Answer N to keep the existing version and continue installing remaining members
• Declining a member upgrade does NOT abort the entire team installation

Team List

$CLI team list

List all locally installed teams with their name, slug, version, and member count.

Team Status

$CLI team status <slug>

Show detailed status of a team: member agents, their install paths, and whether their AGENTS.md contains the team block.

Team Installation Rules

After the user confirms, execute: $CLI team install <slug>

Never execute team install without both: (1) a slug, and (2) explicit user confirmation.

Installation Rules

Present the following two options to the user and wait for their response:

1. new — Create a new agent. The existing agents are not affected.
2. overwrite — Overwrite the main agent (~/.openclaw/workspace). The existing workspace will be backed up automatically.

Important:

• Do NOT execute install until the user explicitly selects one of the above options
• Do NOT use "new" as a default without asking
• Do NOT use "overwrite" unless the user explicitly selects it
• If the user chooses "new" but doesn't specify a name, use the slug as the default name

After the user explicitly selects "new", execute: $CLI install <slug> --name <user-specified name> (add --version <ver> if the user specified a version) After the user explicitly selects "overwrite", execute: $CLI install <slug> --overwrite (add --version <ver> if the user specified a version)

Never execute install without both: (1) a slug, and (2) explicit user confirmation of installation mode.

Export Rules

• MEMORY.md is excluded by default. Only include it if the user explicitly requests it with --include-memory.
• Sensitive files are automatically filtered out during export (.credentials, .env, .secret, .key, .pem).
• After a successful export, remind the user to review the exported ZIP for any sensitive data (API keys, credentials, personal information).
• Export is a purely local operation — it does not require network access.

Error Handling

Workflow

1. Search: Run $CLI search <keyword> to find agentars. Each result includes a slug identifier.
2. Install: If the user did not specify which agentar to install (no slug), ask the user to enter the agentar name/slug. Then confirm installation mode: present [1] new, [2] overwrite; never use overwrite without explicit user selection. Only after you have both slug and mode, execute the install command.
3. Export: If the user did not specify which agent to export, run $CLI export (no --agent) to list agents, present the list to the user, and ask them to choose. Only after the user selects an agent, run $CLI export --agent <id>. Do not export without the user's explicit selection.
4. Rollback: If the user wants to undo an overwrite install, run $CLI rollback to list available backups and restore one.
5. Team Search: Run $CLI team search <keyword> to find teams. Each result includes a slug identifier.
6. Team Install: Confirm the slug with the user. Inform them that member agents will be installed or reused. Only after user confirmation, execute $CLI team install <slug>.
7. Team List/Status: Run $CLI team list to see installed teams or $CLI team status <slug> for detailed member status.