Guía Práctica

Repaso rápido

En el artículo anterior, exploramos los conceptos centrales de los Plugins: son el mecanismo de Claude Code para empaquetar y distribuir flujos de trabajo, integrando Commands, Skills, Agents, Hooks y otros componentes en una sola unidad para compartir con el equipo y distribuir en la comunidad. Este artículo adopta un enfoque práctico y te guiará a través del proceso completo, desde la creación hasta la publicación.

Crea tu primer Plugin

Paso 1: Crear la estructura de directorios

mkdir my-first-plugin
mkdir my-first-plugin/.claude-plugin
mkdir my-first-plugin/commands

Paso 2: Crear el manifiesto del plugin

Define los metadatos de tu plugin en .claude-plugin/plugin.json:

{
  "name": "my-first-plugin",
  "description": "我的第一个 Claude Code 插件",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  }
}

Paso 3: Agregar comandos slash

Crea archivos Markdown en el directorio commands/. Cada archivo corresponde a un comando:

commands/hello.md:

---
description: 向用户发送友好的问候
---

# Hello 命令

请热情地问候用户，并询问今天可以帮助他们做什么。

Paso 4: Probar el plugin

Usa la bandera --plugin-dir para cargar tu plugin local y probarlo:

claude --plugin-dir ./my-first-plugin

Ejecuta el comando en Claude Code:

/my-first-plugin:hello

Paso 5: Agregar argumentos al comando

Los comandos admiten recibir argumentos proporcionados por el usuario. Actualiza hello.md:

---
description: 向指定用户发送个性化问候
---

# Hello 命令

请热情地问候名为 "$ARGUMENTS" 的用户，并询问今天可以帮助他们做什么。

如果用户没有提供名字，就使用"朋友"作为称呼。

Prueba el comando con argumentos:

/my-first-plugin:hello 小明

Marcadores de posición admitidos para argumentos:

• $ARGUMENTS - Toda la entrada del usuario
• $1, $2, $3 - Argumentos individuales

Agregar más componentes

Agregar Skills

Crea un directorio skills/. Cada Skill es una carpeta que contiene un archivo SKILL.md:

my-first-plugin/
├── skills/
│   └── code-review/
│       └── SKILL.md

skills/code-review/SKILL.md:

---
name: code-review
description: 审查代码质量、安全性和可维护性
---

当审查代码时，请检查以下方面：

1. **代码组织**：结构是否清晰
2. **错误处理**：异常是否被妥善处理
3. **安全隐患**：是否存在安全漏洞
4. **测试覆盖**：关键逻辑是否有测试

输出格式：
- 严重问题（必须修复）
- 警告（建议修复）
- 建议（可以改进）

Agregar Subagents

Crea un directorio agents/:

agents/code-reviewer.md:

---
name: code-reviewer
description: 专业的代码审查代理，用于代码质量检查
tools: Read, Grep, Glob, Bash
---

你是一位资深的代码审查专家。

当被调用时：
1. 运行 git diff 查看最近的更改
2. 分析修改的文件
3. 提供结构化的审查反馈

审查清单：
- 代码可读性和命名规范
- 错误处理和边界条件
- 安全漏洞（如注入、敏感信息泄露）
- 性能优化机会

Agregar Hooks

Los Hooks te permiten ejecutar scripts automáticamente cuando ocurren eventos específicos. Crea hooks/hooks.json:

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

Importante: Usa la variable de entorno ${CLAUDE_PLUGIN_ROOT} para referenciar archivos dentro del directorio del plugin, asegurando que las rutas se resuelvan correctamente sin importar dónde esté instalado el plugin.

Crea el script correspondiente scripts/format-code.sh:

#!/bin/bash
# 格式化代码
cd "$CLAUDE_PROJECT_DIR" && make format 2>/dev/null || true

Recuerda asignar permisos de ejecución:

chmod +x scripts/format-code.sh

Agregar servidores MCP

Si tu plugin necesita conectarse a sistemas externos, crea .mcp.json:

{
  "mcpServers": {
    "plugin-database": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
      }
    }
  }
}

Estructura completa del Plugin

Un Plugin con funcionalidad completa podría verse así:

my-plugin/
├── .claude-plugin/
│   └── plugin.json           # 插件清单
├── commands/
│   ├── review.md             # 代码审查命令
│   ├── deploy.md             # 部署命令
│   └── test.md               # 测试命令
├── agents/
│   ├── code-reviewer.md      # 代码审查代理
│   └── debugger.md           # 调试代理
├── skills/
│   └── code-standards/
│       └── SKILL.md          # 代码规范知识
├── hooks/
│   └── hooks.json            # 事件钩子配置
├── scripts/
│   ├── format-code.sh        # 格式化脚本
│   └── run-tests.sh          # 测试脚本
├── .mcp.json                  # MCP 配置
├── LICENSE
├── README.md
└── CHANGELOG.md

El plugin.json correspondiente:

{
  "name": "dev-toolkit",
  "version": "1.0.0",
  "description": "开发者工具箱：代码审查、测试、部署一站式解决方案",
  "author": {
    "name": "Your Team",
    "email": "team@example.com"
  },
  "homepage": "https://github.com/you/dev-toolkit",
  "repository": "https://github.com/you/dev-toolkit",
  "license": "MIT",
  "keywords": ["development", "code-review", "deployment"],
  "commands": "./commands/",
  "agents": "./agents/",
  "skills": "./skills/",
  "hooks": "./hooks/hooks.json",
  "mcpServers": "./.mcp.json"
}

Publicar en el Marketplace

Qué es el Marketplace

El Marketplace es el centro de distribución de Plugins. Puedes entenderlo como una "tienda de plugins": los usuarios pueden instalar tus plugins publicados con un simple comando.

Crear la configuración del Marketplace

Crea .claude-plugin/marketplace.json en tu repositorio de GitHub:

{
  "name": "my-marketplace",
  "owner": {
    "name": "Your Name",
    "email": "you@example.com"
  },
  "plugins": [
    {
      "name": "dev-toolkit",
      "source": "./plugins/dev-toolkit",
      "description": "开发者工具箱",
      "version": "1.0.0"
    },
    {
      "name": "doc-generator",
      "source": {
        "source": "github",
        "repo": "you/doc-generator-plugin"
      },
      "description": "文档生成工具"
    }
  ]
}

Tipos de fuente de plugins

El Marketplace admite múltiples tipos de fuentes:

Ruta relativa (plugins dentro del mismo repositorio):

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

Repositorio de GitHub:

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}

Cualquier repositorio Git:

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

Flujo de publicación

1. Crear un repositorio en GitHub

2. Subir el código:

   git init
   git add .
   git commit -m "Initial release"
   git push origin main

3. Los usuarios agregan tu Marketplace:

   /plugin marketplace add your-username/your-repo

4. Los usuarios instalan plugins:

   /plugin install dev-toolkit@your-marketplace

Instalar y gestionar Plugins

A través del menú interactivo

/plugin

Esto abre una interfaz interactiva donde puedes explorar, instalar, habilitar y deshabilitar plugins.

A través de la línea de comandos

Agregar un Marketplace:

/plugin marketplace add owner/repo           # GitHub
/plugin marketplace add https://example.com/marketplace.json  # URL
/plugin marketplace add ./local-marketplace  # 本地

Instalar plugins:

# 安装到用户范围（默认）
/plugin install formatter@my-marketplace

# 安装到项目范围（团队共享）
/plugin install formatter@my-marketplace --scope project

# 安装到本地范围（gitignored）
/plugin install formatter@my-marketplace --scope local

Otros comandos de gestión:

/plugin enable <plugin>      # 启用插件
/plugin disable <plugin>     # 禁用插件
/plugin uninstall <plugin>   # 卸载插件
/plugin update <plugin>      # 更新插件

Validar plugins

Verifica que la configuración de tu plugin sea correcta antes de publicar:

claude plugin validate .

O dentro de Claude Code:

/plugin validate .

Configuración para colaboración en equipo

Compartir la configuración de plugins en un proyecto

Confirma la configuración de plugins en el control de versiones para que los miembros del equipo la obtengan automáticamente:

.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

Después de que los miembros del equipo clonen el proyecto, estos plugins estarán disponibles automáticamente.

Restricciones empresariales del Marketplace

Para entornos empresariales que requieren un control estricto, puedes restringir los Marketplaces permitidos en la configuración administrada:

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "company/approved-plugins"
    }
  ]
}

Establecerlo como un arreglo vacío [] desactiva completamente los plugins externos.

Referencia de comandos CLI

Mejores prácticas

Mejores prácticas de desarrollo

1. Mantén los Skills enfocados: Cada Skill debe hacer bien una sola cosa; evita diseños que intenten abarcar todo
2. Escribe descripciones claras: Ayuda a Claude a entender cuándo usar tus componentes
3. Prueba primero con tu equipo: Valida internamente antes de distribuir a la comunidad
4. Documenta los cambios de versión: Registra los cambios de cada versión en CHANGELOG.md

Mejores prácticas de estructura de directorios

• Coloca commands/, agents/, skills/ en el directorio raíz del plugin
• Solo coloca plugin.json dentro del directorio .claude-plugin/
• Usa ${CLAUDE_PLUGIN_ROOT} para referenciar archivos dentro del plugin
• Nunca uses ../ para acceder a archivos fuera del plugin

Mejores prácticas de Hooks

1. Los scripts deben ser ejecutables: chmod +x script.sh
2. Usa un shebang para declarar el intérprete: #!/bin/bash
3. Usa la variable ${CLAUDE_PLUGIN_ROOT} para asegurar que las rutas sean correctas
4. Prueba los scripts de forma independiente antes de integrarlos en Hooks

Mejores prácticas de gestión de versiones

Sigue el Semantic Versioning:

• MAJOR (1.0.0 → 2.0.0): Cambios que rompen la compatibilidad
• MINOR (1.0.0 → 1.1.0): Nuevas funcionalidades (compatible con versiones anteriores)
• PATCH (1.0.0 → 1.0.1): Corrección de errores (compatible con versiones anteriores)

Solución de problemas comunes

Migrar desde una configuración existente

Si ya tienes configuraciones en el directorio .claude/, sigue estos pasos para migrarlas a un Plugin:

1. Crear la estructura del Plugin:

   mkdir my-plugin/.claude-plugin

2. Crear plugin.json:

   {
     "name": "my-plugin",
     "description": "从现有配置迁移的插件",
     "version": "1.0.0"
   }

3. Copiar los archivos existentes:

   cp -r .claude/commands my-plugin/
   cp -r .claude/agents my-plugin/
   cp -r .claude/skills my-plugin/

4. Migrar Hooks: Copia la configuración de hooks desde .claude/settings.json a hooks/hooks.json

5. Probar:

   claude --plugin-dir ./my-plugin

Recursos de aprendizaje

Documentación oficial

Repositorios oficiales

Recursos de la comunidad

Lectura recomendada

Perspectivas a futuro

El sistema de Plugins representa un salto cualitativo en la capacidad de extensión de Claude Code. A medida que la comunidad crece, podemos esperar:

• Un ecosistema de plugins más rico: Cubriendo una amplia variedad de escenarios de desarrollo y flujos de trabajo
• Funcionalidades de nivel empresarial: Gestión de permisos y capacidades de auditoría más completas
• Compatibilidad multiplataforma: El estándar abierto de Skills ya ha sido adoptado por múltiples proveedores

Ahora es el momento perfecto para participar. Puedes comenzar con comandos simples, agregar gradualmente Skills y Hooks, y eventualmente construir una solución completa de flujo de trabajo.

Si deseas conocer más sobre el componente Subagent que los Plugins pueden incluir, lee Qué son los Claude Code Subagents.