Contrato de empaquetado de cohortesCopy Anchor Link

Este documento especifica el contrato estable y consumible aguas abajo para el empaquetado de cohortes y los manifiestos de plugin. Un consumidor lee este contrato para enumerar las cohortes y resolver sus destinos nativos por entorno sin volver a derivar el mapeo.

ArtefactosCopy Anchor Link

Forma del manifiesto de cohortesCopy Anchor Link

El manifiesto de cohortes es un objeto de nivel superior con tres claves:

• version — cadena SemVer del manifiesto.
• cohorts[] — una entrada por cohorte. Cada entrada tiene id (del conjunto cerrado core | developer | security | research | ai-engineering | full), name, description y members (un objeto que agrupa los identificadores de miembros por tipo de catálogo: skills / agents / commands / rules / hooks).
• per_harness_targets — el contrato de resolución (más abajo).

Cada identificador de miembro es un nombre estable en kebab-case que corresponde a un artefacto real bajo src/apothem/ (skills/<name>/, agents/<name>.md, commands/<name>.md, rules/<name>.md, o una entrada de hooks — ya sea un hooks/<name>.py ejecutable o un contexto de mensaje consultivo en hooks/messages/<name>.md entregado a través del despachador).

Enumerar cohortesCopy Anchor Link

Un consumidor carga cohort-manifest.yaml, lo valida contra cohort.schema.json y luego itera sobre cohorts[]. Para cada cohorte lee members.<type> para obtener los identificadores de miembros de cada tipo de catálogo.

Resolver los destinos nativos por entorno (sin volver a derivar)Copy Anchor Link

El manifiesto de cohortes no reformula el mapeo de entornos. En su lugar, per_harness_targets.source apunta a lib/propagation-manifest.yaml, la única fuente de verdad. La regla de resolución:

Para un miembro de cohorte de tipo de catálogo T (uno de skills, agents, commands, rules, hooks) y un entorno de destino H (uno de los listados en per_harness_targets.harnesses), el destino nativo del plugin es el campo target de la entrada de lib/propagation-manifest.yaml bajo harnesses.H.install cuyo source coincide con T/.

Por ejemplo, una skill de la cohorte core instalada para claude_code se resuelve, a través de la entrada harnesses.claude_code.install con source: "skills/", a target: "${HARNESS_ROOT}/skills/". La misma skill para opencode se resuelve a ${HARNESS_ROOT}/skills/; para gemini_cli, a ${PROJECT_ROOT}/.gemini/skills/. Los consumidores nunca inventan destinos de entorno: los buscan.

Los marcadores de posición ${HARNESS_ROOT} / ${PROJECT_ROOT} los resuelve cada adaptador de entorno en el momento de la instalación; los consumidores de cohortes tratan el target resuelto de forma literal.

Función del manifiesto de pluginCopy Anchor Link

plugin.schema.json describe un plugin.json — un paquete autodescriptivo de miembros del catálogo (skills / commands / agents / hooks / rules) con un name obligatorio, una version SemVer y una description. Los metadatos opcionales cubren displayName (el nombre que se muestra en lugar de name) y los campos de listado del directorio de plugins: documentationUrl, supportUrl, privacyPolicyUrl y termsOfServiceUrl, cada uno una URL https://, además de una ruta icon dentro del plugin. El paquete de Claude Code generado establece displayName, documentationUrl y supportUrl. El directorio de Anthropic lee los campos de listado y Claude Code los ignora al cargar. La sincronización del marketplace de claude.ai informa los dos enlaces como claves no reconocidas y los elimina, de modo que el marketplace allí muestra "1 with warnings". Esa advertencia es esperada, y el plugin se carga sin cambios. Un manifiesto de plugin es la unidad que un adaptador de entorno materializa en su superficie de plugin nativa; las cohortes seleccionan qué miembros lleva un plugin, y el manifiesto de propagación resuelve dónde aterrizan esos miembros por entorno.

Decisión de empaquetado — un único paquete paraguas, cohortes lógicasCopy Anchor Link

Las cohortes son una capa de selección lógica (este manifiesto), no un conjunto de paquetes separados e instalables de forma independiente. Apothem distribuye un único paquete paraguas que lleva el catálogo completo; el manifiesto de cohortes permite a un consumidor elegir un subconjunto coherente, y el manifiesto de propagación resuelve dónde aterriza cada miembro seleccionado por entorno.

Dividir el catálogo en paquetes separados por cohorte (p. ej., un paquete por cada familia developer / security / research) es alcanzable sin duplicación a nivel del repositorio mediante el patrón de enlaces simbólicos de metaplugin documentado por la superficie de distribución principal: un catálogo de marketplace lista varios plugins de cohorte, y cada directorio de plugin de cohorte contiene enlaces simbólicos hacia el catálogo compartido de fuente única en lugar de copias. Cuando se instala una cohorte, el entorno desreferencia cada enlace simbólico interno del marketplace — copiando el contenido del destino en la caché de esa cohorte —, de modo que la cohorte instalada es autocontenida, mientras que el repositorio conserva una única fuente de verdad conectada mediante enlaces simbólicos (conexión en lugar de redundancia, exactamente como prefiere la disciplina de deduplicación). La lectura anterior de que los paquetes de cohorte «duplican mecánicamente» el catálogo confundía la duplicación de la caché en el momento de la instalación (la copia por plugin habitual del entorno) con la duplicación en el repositorio; el patrón de enlaces simbólicos evita esta última.

Apothem distribuye actualmente un único paquete paraguas porque esa es la superficie de distribución más sencilla, no porque las cohortes sean mecánicamente imposibles. Adoptar la forma por cohorte es un verdadero compromiso entre UX y mantenimiento, no una violación de la deduplicación: la ventaja es una experiencia más granular de «instalar solo esta familia»; los costes son mantener N directorios de enlaces simbólicos de cohorte más sus entradas de marketplace, una superficie de conformidad / pruebas / golden más grande y copias de caché por cohorte en el momento de la instalación. La capa de cohortes lógicas descrita arriba ya ofrece, desde el único paquete, el resultado de selección «instalar solo lo que necesitas»; el empaquetado por cohorte es el siguiente paso cuando se quiera la experiencia de instalación más granular.