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-guidese 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 llamadapr-review-checklistdebe residir en una carpeta llamadapr-review-checklist/, nopr-review/ochecklist/; las discrepancias hacen que una biblioteca sea más difícil de escanear y buscar. - Evita sustantivos genéricos como nombre completo.
helper,assistant,utilityytoolno 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-updatequeprocess-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-reviewes 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
descriptiones 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-draftypr-changelog-entryse 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.mdyticket-schema.mdson claros por sí mismos;notes.mdodata.mdrequieren 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.pyes reutilizable en espíritu y claro en una lista de carpetas;helper1.pyno 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.mdhace que la conexión sea más difícil de verificar de un vistazo.
Preguntas Frecuentes
¿Por qué importa la nomenclatura si la descripción es lo que realmente activa una Habilidad?
La descripción impulsa la activación, pero los nombres son lo que un humano escanea al navegar por una carpeta de Habilidades, y los nombres confusos o vagos hacen mucho más difícil detectar duplicados, lagunas y la Habilidad existente correcta para extender.
¿Cuál es el formato estándar para el campo `name` de una Habilidad?
- Verbo-sustantivo, kebab-case:
format-release-notes,summarize-support-transcript. - El nombre de la carpeta debe coincidir exactamente.
¿Por qué evitar nombres como "helper" o "assistant"?
Describen una categoría, no una acción, por lo que colisionan fácilmente a medida que una biblioteca crece y no le dicen a un compañero de equipo que escanea nada sobre lo que la Habilidad realmente produce.
¿Debo incluir un número de versión en el nombre de una Habilidad, como pr-review-checklist-v2?
- Generalmente no, ya que fragmenta la biblioteca y rompe cualquier referencia existente al nombre original. Un comentario corto de "última actualización" dentro del archivo comunica la misma historia sin dividir el espacio de nombres.
¿Cómo evito que una biblioteca de Habilidades en crecimiento desarrolle Habilidades casi duplicadas?
Verifica las descripciones de las nuevas Habilidades contra las existentes antes de agregarlas, y mantén un índice simple (nombre más propósito de una línea) una vez que la biblioteca crezca más allá de una docena de Habilidades.
¿Deben los archivos de referencia y scripts empaquetados seguir su propio patrón de nomenclatura?
- Sí. Nombres descriptivos y autónomos como
style-guide.mdonormalize-dates.pyson claros sin abrir el archivo, a diferencia de nombres genéricos comonotes.mdohelper1.py.
¿Qué pertenece al campo description en lugar del campo name?
El nombre es un identificador corto y escaneable. La descripción contiene la señal de descubrimiento real (qué hace la Habilidad y cuándo debería activarse) y debe mantenerse libre de detalles de implementación interna como nombres de herramientas o archivos.
¿Cómo debo nombrar un grupo de Habilidades estrechamente relacionadas?
- Dales un prefijo compartido, como
pr-review-checklist,pr-summary-draftypr-changelog-entry, para que se ordenen juntas en una lista de carpetas y señalen visiblemente que forman parte de una familia.
¿Qué debo hacer con una Habilidad que ha dejado de usarse?
Retírala o fusionarla en lugar de dejarla en su lugar. Una Habilidad no utilizada con un nombre similar a una activa es una fuente común de colisiones accidentales y confusión más adelante.
¿Existe una única lista de verificación de nomenclatura obligatoria que cada equipo deba seguir?
- No exactamente; los patrones de nomenclatura (kebab-case, nombres de carpetas coincidentes, evitar sustantivos genéricos) son casi universales, pero los patrones organizativos (prefijos, indexación, retiro) son decisiones que escalan con la cantidad de Habilidades que un equipo tiene realmente.
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.