Claude Code Plugin Reference
Contratos de hook, habilidad, comando y plugin.json de Claude Code verificados contra un repositorio real
Probado · Funciona
Qué hace
Un documento de referencia que cubre la maquinaria de plugins de Claude Code: contratos de campos plugin.json y metadata.json, frontmatter de SKILL.md, frontmatter de comando y agente, registro de hooks en hooks.json, el contrato de payload JSON de stdin, formas de veredicto permissionDecision, semántica de códigos de salida, e instalación y bloqueo de versión del marketplace. Se activa cuando se está creando o depurando un plugin, habilidad, comando, agente o hook de Claude Code. El contenido se compila del repositorio athola/claude-night-market, por lo que aproximadamente un tercio es convención local del repositorio (nombres de plugins night-market, scripts sanctum, restricciones de host Python 3.9) junto con los contratos de arnés portátiles.
Informe de la prueba
Se clonó el repositorio, se confirmó que el frontmatter se analiza con nombre + una descripción de 158 caracteres, y se verificaron 13 archivos citados (check_plugin_hooks.py, validate_budget.py, hook_io.py, tdd_bdd_gate.py, marketplace.json, python39-compat.yml, ...) — todos presentes; no hay curl|sh, base64 o texto de inyección en ninguna parte del archivo de 511 líneas. La instalación se ejecutó en un HOME mktemp nuevo y colocó SKILL.md en ~/.claude/skills/claude-code-plugin-reference/SKILL.md. Prueba de salida: escribí un hook PreToolUse que bloqueaba `git commit --no-verify` dos veces, extraje ambos cuerpos de Python y los ejecuté — la línea base imprimió permissionDecision "block" (no uno de allow/deny/ask) y salió con código 2, y falló con un JSONDecodeError no capturado (código 1) tanto en `echo not-json` como en stdin vacío; la versión seguida por la habilidad imprimió "deny", salió con código 0 en los tres casos y envió diagnósticos a stderr. También ejecuté la propia puerta del repositorio contra ambos manifiestos: `python3 scripts/check_plugin_hooks.py` rechazó mi plugin.json de línea base (código 1, "hooks array contains './hooks/hooks.json'") y aceptó el seguido por la habilidad (código 0). Frases de activación — DEBERÍA cargarse: "How do I register a PreToolUse hook in my plugin's hooks.json?", "My plugin hook isn't firing, it reads CLAUDE_TOOL_INPUT and gets nothing", "What frontmatter does a SKILL.md need and how does Skill(plugin:name) resolve?" — lo cargaría para las tres. NO DEBERÍA: "Run the test suite and publish 1.9.16 to the marketplace" (el "Do not use for ops" explícito de la descripción me dirige a night-market-operations, aunque exista una sección Marketplace) y "Write a Python CLI that parses JSON from stdin" (sin contexto de plugin) — rechacé ambos. La documentación perdió un punto: el cuerpo afirma que `"hooks": []` está "verified across all 23 manifests" pero en disco solo 11 de 23 llevan la clave y 12 la omiten por completo (mismo efecto, redacción incorrecta), y el "used here" de la descripción nunca nombra el repositorio, por lo que un instalador independiente obtiene punteros solo de night-market (/sanctum:update-plugins, plugins/imbue, habilidades hermanas night-market-*) mezclados con hechos de arnés portátiles. No pude ejecutar Python 3.9 localmente, por lo que la afirmación datetime.UTC / py39 no está verificada por ejecución; todas las demás afirmaciones que verifiqué (10s registrados vs 8s de tiempo de espera interno de herald, la anomalía de advertencia/bloqueo vow_no_ai_attribution, DESCRIPTION_MAX = 160, el docstring stdin-first de hook_io) coincidieron exactamente con la fuente.
Probado el: 2026-07-21 · Claude Code 2.x (agent harness)
Instalación
git clone --depth 1 https://github.com/athola/claude-night-market.git /tmp/claude-code-plugin-reference-src mkdir -p ~/.claude/skills cp -R /tmp/claude-code-plugin-reference-src/.claude/skills/claude-code-plugin-reference ~/.claude/skills/claude-code-plugin-reference # Single markdown file, no deps, no scripts, nothing to run. # The skill lives in the repo's own .claude/skills/ (a project skill), not in a plugin. # The ~15 scripts it cites (scripts/check_plugin_hooks.py, plugins/abstract/scripts/validate_budget.py, # plugins/sanctum/scripts/update_versions.py, ...) all exist in the clone at /tmp/claude-code-plugin-reference-src # but NOT next to the installed skill, so the "re-verify" commands in its Provenance section # only run from inside a night-market checkout. Keep the clone if you want them. # Plugin-marketplace alternative does NOT ship this skill: /plugin marketplace add athola/claude-night-market # installs the plugins under plugins/, and this file is not registered in any plugin.json.
Comandos y prompts de ejemplo
/claude-code-plugin-referenceContratos de hook, habilidad, comando y plugin.json de Claude Code verificados contra un repositorio real
Los skills se activan con peticiones en lenguaje natural, sin comandos que memorizar. Tras instalarlo, prompts como estos lo activan (en inglés):
Explain how Claude Code skills are triggeredHelp me author a new Claude Code pluginDebug why my hook isn't firing correctly