Referencia de plugins

​

Referencia de componentes de plugins

​

Skills

skills/
├── pdf-processor/
│   ├── SKILL.md
│   ├── reference.md (opcional)
│   └── scripts/ (opcional)
└── code-reviewer/
    └── SKILL.md

• Los skills y comandos se descubren automáticamente cuando se instala el plugin
• Claude puede invocarlos automáticamente según el contexto de la tarea
• Los skills pueden incluir archivos de apoyo junto a SKILL.md

​

Agents

---
name: agent-name
description: En qué se especializa este agent y cuándo Claude debe invocarlo
model: sonnet
effort: medium
maxTurns: 20
disallowedTools: Write, Edit
---

Prompt del sistema detallado para el agent describiendo su rol, experiencia y comportamiento.

• Los agents aparecen en la interfaz /agents
• Claude puede invocar agents automáticamente según el contexto de la tarea
• Los agents pueden ser invocados manualmente por los usuarios
• Los agents del plugin funcionan junto con los agents integrados de Claude

​

Hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

• command: ejecutar comandos de shell o scripts
• http: enviar el JSON del evento como una solicitud POST a una URL
• prompt: evaluar un prompt con un LLM (usa el marcador de posición $ARGUMENTS para el contexto)
• agent: ejecutar un verificador agentic con herramientas para tareas de verificación complejas

​

MCP servers

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    },
    "plugin-api-client": {
      "command": "npx",
      "args": ["@company/mcp-server", "--plugin-mode"],
      "cwd": "${CLAUDE_PLUGIN_ROOT}"
    }
  }
}

• Los servidores MCP del plugin se inician automáticamente cuando se habilita el plugin
• Los servidores aparecen como herramientas MCP estándar en el kit de herramientas de Claude
• Las capacidades del servidor se integran sin problemas con las herramientas existentes de Claude
• Los servidores del plugin se pueden configurar independientemente de los servidores MCP del usuario

​

LSP servers

• Diagnósticos instantáneos: Claude ve errores y advertencias inmediatamente después de cada edición
• Navegación de código: ir a definición, encontrar referencias e información al pasar el ratón
• Conciencia del lenguaje: información de tipo y documentación para símbolos de código

{
  "go": {
    "command": "gopls",
    "args": ["serve"],
    "extensionToLanguage": {
      ".go": "go"
    }
  }
}

{
  "name": "my-plugin",
  "lspServers": {
    "go": {
      "command": "gopls",
      "args": ["serve"],
      "extensionToLanguage": {
        ".go": "go"
      }
    }
  }
}

​

Alcances de instalación de plugins

​

Esquema del manifiesto del plugin

​

Esquema completo

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "[email protected]",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "commands": ["./custom/commands/special.md"],
  "agents": "./custom/agents/",
  "skills": "./custom/skills/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json"
}

​

Campos requeridos

​

Campos de metadatos

​

Campos de ruta de componentes

​

Configuración del usuario

{
  "userConfig": {
    "api_endpoint": {
      "description": "El endpoint de API de tu equipo",
      "sensitive": false
    },
    "api_token": {
      "description": "Token de autenticación de API",
      "sensitive": true
    }
  }
}

​

Canales

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": { "description": "Token del bot de Telegram", "sensitive": true },
        "owner_id": { "description": "Tu ID de usuario de Telegram", "sensitive": false }
      }
    }
  ]
}

​

Reglas de comportamiento de rutas

• Si commands/ existe, se carga además de las rutas de comandos personalizadas
• Todas las rutas deben ser relativas a la raíz del plugin y comenzar con ./
• Los comandos de rutas personalizadas utilizan las mismas reglas de nomenclatura y espacios de nombres
• Se pueden especificar múltiples rutas como arrays para flexibilidad

{
  "commands": [
    "./specialized/deploy.md",
    "./utilities/batch-process.md"
  ],
  "agents": [
    "./custom-agents/reviewer.md",
    "./custom-agents/tester.md"
  ]
}

​

Variables de entorno

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/process.sh"
          }
        ]
      }
    ]
  }
}

​

Directorio de datos persistente

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
          }
        ]
      }
    ]
  }
}

{
  "mcpServers": {
    "routines": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
      "env": {
        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
      }
    }
  }
}

​

Almacenamiento en caché de plugins y resolución de archivos

• A través de claude --plugin-dir, durante la duración de una sesión.
• A través de un marketplace, instalado para sesiones futuras.

​

Limitaciones de traversal de rutas

​

Trabajar con dependencias externas

# Dentro de tu directorio de plugin
ln -s /path/to/shared-utils ./shared-utils

​

Estructura del directorio del plugin

​

Diseño estándar del plugin

enterprise-plugin/
├── .claude-plugin/           # Directorio de metadatos (opcional)
│   └── plugin.json             # manifiesto del plugin
├── commands/                 # Ubicación de comando predeterminada
│   ├── status.md
│   └── logs.md
├── agents/                   # Ubicación de agent predeterminada
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── skills/                   # Skills del Agent
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── hooks/                    # Configuraciones de hooks
│   ├── hooks.json           # Configuración principal de hooks
│   └── security-hooks.json  # Hooks adicionales
├── settings.json            # Configuración predeterminada para el plugin
├── .mcp.json                # Definiciones del servidor MCP
├── .lsp.json                # Configuraciones del servidor LSP
├── scripts/                 # Scripts de hooks y utilidades
│   ├── security-scan.sh
│   ├── format-code.py
│   └── deploy.js
├── LICENSE                  # Archivo de licencia
└── CHANGELOG.md             # Historial de versiones

​

Referencia de ubicaciones de archivos

​

Referencia de comandos CLI

​

plugin install

claude plugin install <plugin> [options]

• <plugin>: Nombre del plugin o plugin-name@marketplace-name para un marketplace específico

# Instalar en alcance de usuario (predeterminado)
claude plugin install formatter@my-marketplace

# Instalar en alcance de proyecto (compartido con el equipo)
claude plugin install formatter@my-marketplace --scope project

# Instalar en alcance local (ignorado por git)
claude plugin install formatter@my-marketplace --scope local

​

plugin uninstall

claude plugin uninstall <plugin> [options]

• <plugin>: Nombre del plugin o plugin-name@marketplace-name

​

plugin enable

claude plugin enable <plugin> [options]

• <plugin>: Nombre del plugin o plugin-name@marketplace-name

​

plugin disable

claude plugin disable <plugin> [options]

• <plugin>: Nombre del plugin o plugin-name@marketplace-name

​

plugin update

claude plugin update <plugin> [options]

• <plugin>: Nombre del plugin o plugin-name@marketplace-name

​

Herramientas de depuración y desarrollo

​

Comandos de depuración

• Qué plugins se están cargando
• Cualquier error en los manifiestos del plugin
• Registro de comandos, agents y hooks
• Inicialización del servidor MCP

​

Problemas comunes

​

Mensajes de error de ejemplo

• Invalid JSON syntax: Unexpected token } in JSON at position 142: busca comas faltantes, comas extra o cadenas sin comillas
• Plugin has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Required: falta un campo requerido
• Plugin has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...: error de sintaxis JSON

• Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.: la ruta del comando existe pero no contiene archivos de comando válidos
• Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.: la ruta source en marketplace.json apunta a un directorio inexistente
• Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.: elimina definiciones de componentes duplicadas o elimina strict: false en la entrada del marketplace

​

Solución de problemas de hooks

1. Verifica que el script sea ejecutable: chmod +x ./scripts/your-script.sh
2. Verifica la línea shebang: La primera línea debe ser #!/bin/bash o #!/usr/bin/env bash
3. Verifica que la ruta use ${CLAUDE_PLUGIN_ROOT}: "command": "${CLAUDE_PLUGIN_ROOT}/scripts/your-script.sh"
4. Prueba el script manualmente: ./scripts/your-script.sh

1. Verifica que el nombre del evento sea correcto (sensible a mayúsculas): PostToolUse, no postToolUse
2. Verifica que el patrón del matcher coincida con tus herramientas: "matcher": "Write|Edit" para operaciones de archivo
3. Confirma que el tipo de hook sea válido: command, http, prompt, o agent

​

Solución de problemas del servidor MCP

1. Verifica que el comando exista y sea ejecutable
2. Verifica que todas las rutas usen la variable ${CLAUDE_PLUGIN_ROOT}
3. Verifica los registros del servidor MCP: claude --debug muestra errores de inicialización
4. Prueba el servidor manualmente fuera de Claude Code

1. Asegúrate de que el servidor esté correctamente configurado en .mcp.json o plugin.json
2. Verifica que el servidor implemente correctamente el protocolo MCP
3. Busca tiempos de espera de conexión en la salida de depuración

​

Errores de estructura de directorio

my-plugin/
├── .claude-plugin/
│   └── plugin.json      ← Solo el manifiesto aquí
├── commands/            ← A nivel de raíz
├── agents/              ← A nivel de raíz
└── hooks/               ← A nivel de raíz

1. Ejecuta claude --debug y busca mensajes “loading plugin”
2. Verifica que cada directorio de componentes esté listado en la salida de depuración
3. Verifica que los permisos de archivo permitan leer los archivos del plugin

​

Referencia de distribución y versionado

​

Gestión de versiones

{
  "name": "my-plugin",
  "version": "2.1.0"
}

• MAJOR: Cambios de ruptura (cambios de API incompatibles)
• MINOR: Nuevas características (adiciones compatibles hacia atrás)
• PATCH: Correcciones de errores (correcciones compatibles hacia atrás)

• Comienza en 1.0.0 para tu primer lanzamiento estable
• Actualiza la versión en plugin.json antes de distribuir cambios
• Documenta los cambios en un archivo CHANGELOG.md
• Usa versiones previas al lanzamiento como 2.0.0-beta.1 para pruebas

​

Ver también

• Plugins - Tutoriales y uso práctico
• Marketplaces de plugins - Crear y gestionar marketplaces
• Skills - Detalles de desarrollo de skills
• Subagents - Configuración y capacidades del agent
• Hooks - Manejo de eventos y automatización
• MCP - Integración de herramientas externas
• Configuración - Opciones de configuración para plugins