# Skill para Claude Code

> plazbot skill: instala la skill que le enseña a Claude Code y a otros agentes de IA a usar el CLI de Plazbot

Fuente: https://developers.plazbot.com/cli/ia/skill/

### Instalar la skill para Claude Code

Instala una skill (un archivo `SKILL.md`) que le explica a Claude Code cómo usar el CLI de Plazbot: qué comandos hay, cómo leer su JSON, cuándo pedir confirmación y qué endpoints consultar con [`plazbot api`](https://developers.plazbot.com/cli/ia/api). Con la skill instalada puedes pedirle cosas como "¿por qué falló la última campaña?" o "busca el contacto +51912345678 y muéstrame su conversación", y Claude las resuelve con el CLI.

```bash
plazbot skill install [opciones]
plazbot skill show
```

### Parámetros

| Parámetro | Flag | Requerido | Descripción |
|-----------|------|-----------|-------------|
| Proyecto | `--project` | No | Instala en `./.claude/skills` (solo este repositorio) en lugar de `~/.claude/skills` |
| Carpeta | `--dir <path>` | No | Instala en otra carpeta de skills |
| JSON | `--json` | No | Imprime el resultado en JSON |
| Confirmar | `-y, --yes` | No | Reemplaza una skill existente sin preguntar |

`plazbot skill show` imprime la skill en Markdown, sin instalarla.

### Ejemplos

```bash
# Instalar para todos los proyectos (~/.claude/skills/plazbot-cli)
plazbot skill install

# Instalar solo en este repositorio
plazbot skill install --project

# Leer la skill
plazbot skill show
```

### Resultado

```text
Skill installed: /Users/tu/.claude/skills/plazbot-cli/SKILL.md
Claude Code loads it in new sessions. Try: "list my latest Plazbot campaigns".
```

Claude Code carga la skill en las sesiones nuevas. Si ya existía una versión distinta, el CLI pide confirmar el reemplazo. Al actualizar el CLI, vuelve a ejecutar `plazbot skill install` para tener la skill de la nueva versión.

### Salida JSON

```json
{
"installed": true,
"path": "/Users/tu/.claude/skills/plazbot-cli/SKILL.md",
"updated": false
}
```

`updated` es `true` cuando reemplazó una skill anterior distinta.

### Qué le enseña la skill

- Usar siempre `--json` y leer los errores de stderr (`{"error": {...}}`, código de salida `1`).
- Empezar con `plazbot whoami --verify --json` para comprobar la sesión.
- Descubrir comandos con [`plazbot commands --json`](https://developers.plazbot.com/cli/ia/commands) antes de adivinar.
- Leer libremente y escribir solo cuando el usuario pidió ese cambio, agregando `--yes` únicamente para esa acción.
- Trabajar con varios workspaces con `-w` y `-z`, y paginar con `--limit`, `--cursor` y `--all`.
- Una tabla con los comandos propios, los endpoints útiles para [`plazbot api`](https://developers.plazbot.com/cli/ia/api), los prefijos de ID (`con_`, `cam_`, `mot_`...) y recetas de soporte.

### Recomendado: sesión de solo lectura

Para que un agente de IA trabaje sin riesgo de cambiar datos, inicia sesión con un token de solo lectura:

```bash
plazbot login --read-only
plazbot skill install
```

Con ese token la API solo acepta consultas (GET). Cualquier cambio falla con el código `read_only`. Más detalles en [Usar el CLI con IA y scripts](https://developers.plazbot.com/cli/ia/scripting).

### Errores comunes

| Mensaje | Causa | Solución |
|---------|-------|----------|
| `This action needs confirmation and there is no interactive terminal.` | Ya hay una skill distinta y no hay terminal | Agrega `--yes` |
| `The skill file is missing from this installation.` | Instalación del CLI incompleta | Reinstala: `npm i -g plazbot-cli` |