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 @-mention typeahead bajo su nombre con alcance, como my-plugin:code-reviewer, una vez que el plugin está habilitado
• 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
• mcp_tool: llamar a una herramienta en un servidor MCP configurado
• 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"]
    }
  }
}

• 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"
      }
    }
  }
}

​

Monitors

[
  {
    "name": "deploy-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
    "description": "Cambios de estado de implementación"
  },
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Registro de errores de la aplicación",
    "when": "on-skill-invoke:debug"
  }
]

​

Themes

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

​

Alcances de instalación de plugins

​

Plugins de directorio de skills

​

Elija dónde se carga el plugin

• Los servidores MCP que declara pasan por la misma aprobación por servidor que un .mcp.json del proyecto
• Los servidores LSP se inician solo después de que confíe en el espacio de trabajo
• Los monitores de fondo no se cargan

​

Editar, recargar y deshabilitar un plugin de directorio de skills

claude plugin disable my-tool@skills-dir

​

Esquema del manifiesto del plugin

​

Esquema completo

{
  "name": "plugin-name",
  "displayName": "Plugin Name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": {
    "themes": "./themes/",
    "monitors": "./monitors.json"
  },
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

​

Campos requeridos

​

Campos no reconocidos

claude plugin validate ./my-plugin --strict

​

Campos de metadatos

​

Habilitación predeterminada

• La configuración del usuario: una entrada para el plugin en enabledPlugins en cualquier alcance de configuración. Una vez escrita, persiste en actualizaciones y reinstalaciones del plugin, por lo que cambiar defaultEnabled en una versión posterior no cambia un usuario existente.
• Un requisito de dependencia: cuando un plugin es requerido por otro que está activo, Claude Code escribe true para él en el tiempo de instalación o habilitación. Eso le da una configuración explícita, por lo que su propio predeterminado ya no se aplica. Consulte Habilitar o deshabilitar un plugin con dependencias.

​

Campos de ruta de componentes

​

Componentes experimentales

​

Configuración del usuario

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Su endpoint de API del equipo"
    },
    "api_token": {
      "type": "string",
      "title": "API token",
      "description": "Token de autenticación de API",
      "sensitive": true
    }
  }
}

​

Canales

{
  "channels": [
    {
      "server": "telegram",
      "userConfig": {
        "bot_token": {
          "type": "string",
          "title": "Bot token",
          "description": "Token del bot de Telegram",
          "sensitive": true
        },
        "owner_id": {
          "type": "string",
          "title": "Owner ID",
          "description": "Su ID de usuario de Telegram"
        }
      }
    }
  ]
}

​

Reglas de comportamiento de rutas

• Reemplaza el predeterminado: commands, agents, outputStyles, experimental.themes, experimental.monitors. Por ejemplo, cuando el manifiesto especifica commands, el directorio predeterminado commands/ no se escanea. Para mantener el predeterminado y añadir más, enumérelo explícitamente: "commands": ["./commands/", "./extras/"]
• Se añade al predeterminado: skills. El directorio predeterminado skills/ siempre se escanea, y los directorios enumerados en skills se cargan junto a él. Excepción: para una entrada del marketplace cuya source se resuelve a la raíz del marketplace, declarar subdirectorios específicos reemplaza el escaneo predeterminado de skills/
• Reglas de fusión propias: hooks, MCP servers y LSP servers. Consulte cada sección para ver cómo se combinan múltiples fuentes

• Todas las rutas deben ser relativas a la raíz del plugin y comenzar con ./
• Los componentes de rutas personalizadas utilizan las mismas reglas de nomenclatura y espacios de nombres
• Se pueden especificar múltiples rutas como arrays
• Cuando una ruta de skill apunta a un directorio que contiene un SKILL.md directamente, por ejemplo "skills": ["./"] apuntando a la raíz del plugin, el campo frontmatter name en SKILL.md determina el nombre de invocación de la skill. Esto proporciona un nombre estable independientemente del directorio de instalación. Si name no se establece en el frontmatter, el nombre base del directorio se usa como alternativa.

{
  "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 o claude --plugin-url, durante la duración de una sesión.
• A través de un marketplace, instalado para sesiones futuras.

​

Limitaciones de traversal de rutas

​

Compartir archivos dentro de un marketplace con enlaces simbólicos

• Dentro del directorio propio del plugin: el enlace simbólico se preserva como un enlace simbólico relativo en la caché, por lo que sigue resolviendo al destino copiado en tiempo de ejecución.
• En otro lugar dentro del mismo marketplace: el enlace simbólico se desreferencia. El contenido del destino se copia en la caché en su lugar. Esto permite que el directorio skills/ de un meta-plugin se vincule a skills definidas por otros plugins en el marketplace.
• Fuera del marketplace: el enlace simbólico se omite por seguridad. Esto evita que los plugins extraigan archivos arbitrarios del host, como rutas del sistema, en la caché.

ln -s ../../shared-plugin/skills/foo ./skills/foo

​

Estructura del directorio del plugin

​

Diseño estándar del plugin

enterprise-plugin/
├── .claude-plugin/           # Directorio de metadatos (opcional)
│   └── plugin.json             # manifiesto del plugin
├── skills/                   # Skills
│   ├── code-reviewer/
│   │   └── SKILL.md
│   └── pdf-processor/
│       ├── SKILL.md
│       └── scripts/
├── commands/                 # Skills como archivos .md planos
│   ├── status.md
│   └── logs.md
├── agents/                   # Definiciones de subagent
│   ├── security-reviewer.md
│   ├── performance-tester.md
│   └── compliance-checker.md
├── output-styles/            # Definiciones de estilo de salida
│   └── terse.md
├── themes/                   # Definiciones de tema de color
│   └── dracula.json
├── monitors/                 # Configuraciones de monitor de fondo
│   └── monitors.json
├── hooks/                    # Configuraciones de hooks
│   ├── hooks.json           # Configuración principal de hooks
│   └── security-hooks.json  # Hooks adicionales
├── bin/                      # Ejecutables del plugin añadidos a PATH
│   └── my-tool               # Invocable como comando desnudo en herramienta Bash
├── 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 init

claude plugin init <name> [options]

• <name>: Nombre del plugin. Se convierte en el espacio de nombres de la skill y el nombre del directorio bajo ~/.claude/skills/, por lo que no puede contener espacios ni separadores de ruta.

# Crear un plugin mínimo
claude plugin init my-helper

# Crear con carpetas de skill y hook
claude plugin init my-helper --with skills hooks

# Sobrescribir un scaffold existente
claude plugin init my-helper --force

​

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 prune

claude plugin prune [options]

​

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

​

plugin list

claude plugin list [options]

​

plugin details

claude plugin details <name>

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

• Always-on: tokens añadidos a cada sesión por el texto de listado del plugin, como descripciones de skills, descripciones de agents, y nombres de comandos, independientemente de si algún componente se activa.
• On-invoke: tokens que cuesta un componente cuando se activa. Se muestra por componente, no como total del plugin, porque una sesión típica invoca solo un subconjunto de componentes.

dependency-guard 1.2.0
  Dependency analysis for Claude Code sessions
  Source: dependency-guard@example-marketplace

Component inventory
  Skills (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  (harness-only — no model context cost)
  MCP servers (0)
  LSP servers (0)

Projected token cost
  Always-on:   ~180 tok   added to every session

Per-component (rounded)
  component            always-on  on-invoke
  scan-dependencies        ~100      ~2400
  review-changes            ~80      ~1800

  On-invoke cost is paid each time a skill or agent fires.
  Token counts are estimates and may differ from actual usage.

​

plugin tag

claude plugin tag [options]

​

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 skills, 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: busque 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.: elimine definiciones de componentes duplicadas o elimine strict: false en la entrada del marketplace

​

Solución de problemas de hooks

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

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

​

Solución de problemas del servidor MCP

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

1. Asegúrese de que el servidor esté correctamente configurado en .mcp.json o plugin.json
2. Verifique que el servidor implemente correctamente el protocolo MCP
3. Busque 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. Ejecute claude --debug y busque mensajes “loading plugin”
2. Verifique que cada directorio de componentes esté listado en la salida de depuración
3. Verifique que los permisos de archivo permitan leer los archivos del plugin

​

Referencia de distribución y versionado

​

Gestión de versiones

1. El campo version en el plugin.json del plugin
2. El campo version en la entrada del marketplace del plugin en marketplace.json
3. El SHA del commit de git del origen del plugin, para fuentes github, url, git-subdir y relative-path en un marketplace alojado en git
4. unknown, para fuentes npm o directorios locales que no estén dentro de un repositorio de git

​

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