Referencia de plugins

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

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

​

Monitors

[
  {
    "name": "deploy-status",
    "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh ${user_config.api_endpoint}",
    "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

​

Esquema del manifiesto del plugin

​

Esquema completo

{
  "name": "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 de metadatos

​

Campos de ruta de componentes

​

Componentes experimentales

​

Configuración del usuario

{
  "userConfig": {
    "api_endpoint": {
      "type": "string",
      "title": "API endpoint",
      "description": "Tu 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": "Tu 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éralo 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
• Reglas de fusión propias: hooks, MCP servers y LSP servers. Consulta 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 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.

security-guidance 1.2.0
  Real-time security analysis for Claude Code sessions
  Source: security-guidance@claude-code-marketplace

Component inventory
  Skills (2)  scan-dependencies, review-changes
  Agents (0)
  Hooks (1)  (harness-only — no model context cost)
  MCP 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: 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, mcp_tool, 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

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