Convenciones de Nomenclatura y Patrones de Metadatos para Habilidades Descubribles

Una sola Habilidad puede arreglárselas con un nombre poco claro. Una biblioteca de treinta Habilidades no puede.

Los patrones de nomenclatura y metadatos importan menos por cómo se activa una Habilidad individual (ese es el trabajo del campo description), y más por cómo un equipo completo mantiene su biblioteca de Habilidades organizada, escaneable y libre de duplicados cercanos a medida que crece.

Esta página recopila los patrones que mantienen legible una biblioteca de Habilidades: para Claude, y para las personas que la construyen y mantienen. Esta es una lista de propósito general de hábitos de nomenclatura y metadatos en lugar de una única lista de verificación fija; no todos los elementos se aplicarán a la configuración de cada equipo.

Cómo Usar Esta Lista

• Aplica estos patrones al nombrar nuevas Habilidades, no como una auditoría única de una biblioteca existente (aunque también es una lista de verificación de auditoría razonable).
• Trata los elementos de nomenclatura como casi obligatorios y los elementos organizativos como decisiones que escalan con el tamaño de la biblioteca.
• Revisa esta página cada vez que el recuento de Habilidades de un equipo crezca más allá de lo que cabe cómodamente en la lista de un solo directorio.

Nombrando la Habilidad en Sí

• Usa el formato kebab-case de verbo-sustantivo para el campo name. format-release-notes, summarize-support-transcript, apply-style-guide se leen claramente de un vistazo y describen una acción, no una categoría vaga.
• Haz que el nombre de la carpeta coincida exactamente con el campo name. Una Habilidad llamada pr-review-checklist debe residir en una carpeta llamada pr-review-checklist/, no pr-review/ o checklist/; las discrepancias hacen que una biblioteca sea más difícil de escanear y buscar.
• Evita sustantivos genéricos como nombre completo. helper, assistant, utility y tool no describen nada sobre lo que la Habilidad realmente hace, y colisionan fácilmente una vez que aparece una segunda Habilidad "helper".
• Nombra el resultado, no el proceso, cuando ambos divergen. Una Habilidad que lee notas de reuniones y produce una actualización de estado se llama mejor draft-status-update que process-meeting-notes; el resultado es generalmente lo que un compañero de equipo recuerda haber querido.
• Mantén los nombres lo suficientemente cortos como para escanearlos en una lista de carpetas. Un nombre como summarize-and-format-and-tag-support-conversations-for-review es preciso pero ilegible; recorta a la acción y objeto esenciales.

Escribiendo el Campo description

• Trata la descripción como la señal principal de descubrimiento, no el nombre. El nombre ayuda a un humano a escanear una carpeta; la description es lo que Claude realmente coincide con una tarea. Consulta Escribir una Descripción de Habilidad Efectiva que Claude Disparará para ver el patrón completo.
• Indica el resultado concreto en la primera oración. "Resume una transcripción de soporte al cliente en un ticket estructurado" es mejor que "ayuda con el soporte", tanto para un humano que escanea descripciones como para que coincida con solicitudes reales.
• Incluye una cláusula "Usar cuando..." nombrando el lenguaje de activación real. Esta es la oración de mayor apalancamiento en todo el archivo para mantener la Habilidad descubrible.
• Mantén la descripción libre de detalles de implementación interna. Los nombres de herramientas, nombres de archivos y recuentos de pasos internos pertenecen al cuerpo de las instrucciones, no a la descripción; añaden longitud sin añadir descubribilidad.

Organizando una Biblioteca de Habilidades en Crecimiento

• Agrupa Habilidades relacionadas con un prefijo de nombre compartido. pr-review-checklist, pr-summary-draft y pr-changelog-entry se ordenan juntos en una lista de carpetas y señalan de un vistazo que forman parte de una familia.
• Verifica descripciones casi duplicadas antes de agregar una nueva Habilidad. Si la descripción de una nueva Habilidad coincidiera plausiblemente con las mismas tareas que una existente, esa superposición necesita resolverse: o bien limita una, o bien integra la nueva tarea en la Habilidad existente como una rama.
• Mantén un índice corto de lo que hace cada Habilidad, separado de las Habilidades mismas. A medida que una biblioteca crece más allá de una docena de Habilidades, una lista simple (nombre, propósito de una línea) ahorra a un compañero de equipo tener que abrir cada carpeta para encontrar la correcta.
• Retira o fusiona Habilidades que dejan de usarse. Una Habilidad no utilizada con un nombre similar a una activa es una fuente común de colisiones accidentales más adelante; eliminarla (o fusionar sus partes útiles) mantiene limpio el espacio de nombres de la biblioteca.
• Versiona informalmente con un comentario corto, no un sufijo de nombre. pr-review-checklist-v2/ fragmenta la biblioteca y rompe cualquier referencia existente; un comentario de una línea "última actualización" dentro de SKILL.md comunica lo mismo sin dividir el nombre.

Nombrando Archivos Empaquetados de Forma Consistente

• Da a los archivos de referencia empaquetados nombres descriptivos y autónomos. style-guide.md y ticket-schema.md son claros por sí mismos; notes.md o data.md requieren abrir el archivo para saber qué contiene.
• Antepón a los scripts empaquetados lo que hacen, no la Habilidad en la que residen. normalize-dates.py es reutilizable en espíritu y claro en una lista de carpetas; helper1.py no es ni lo uno ni lo otro.
• Haz referencia a los archivos empaquetados por su nombre exacto dentro de las instrucciones. Esto es tanto una disciplina de nomenclatura como una estructural: un paso que dice "el archivo de referencia" en lugar de nombrar reference.md hace que la conexión sea más difícil de verificar de un vistazo.

Preguntas Frecuentes

Relacionados

• Escribir una Descripción de Habilidad Efectiva que Claude Disparará - el campo que realmente impulsa la activación, distinto de la nomenclatura.
• Conceptos Básicos de Diseño y Empaquetado de Habilidades - un primer SKILL.md funcional con un nombre y descripción correctamente formados.
• Errores Comunes que Hacen que una Habilidad Sea Difícil de Encontrar o Usar para Claude - fallos de nomenclatura y metadatos junto con fallos de descripción.
• Tipos Comunes de Habilidades de Agente que los Equipos Construyen Primero - Habilidades típicas que una biblioteca de nomenclatura termina organizando.

Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5. Los nombres de modelos, precios y características de productos cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.