Deja de dispersar recursos de IA: gestiona skills, rules y MCP con Bear.CTXPM

Cuando los archivos de IA se acumulan

Si trabajas el tiempo suficiente con agentes de código, el repositorio se llena de mucho más que prompts. Hay rules que limitan el estilo del código, skills para tareas rutinarias, specs que describen los límites del producto, configuraciones MCP que conectan servicios externos y memories de decisiones pasadas. Parte viene de comunidades open source, parte pertenece al equipo y parte solo importa a un proyecto concreto.

Meterlo todo en el repo funciona al principio. El problema aparece después, cuando el proyecto crece, cambias de agente o vuelves a él tras meses. ¿Qué archivos van en Git? ¿Ha cambiado algún recurso externo? ¿Una regla concreta es para todo el equipo o solo para este repositorio? Sin límites claros, toda la configuración se convierte en un caos.

Ese caos es el punto de partida de Bear.CTXPM. El nombre abrevia Context Package Manager. Es un protocolo open source para gestionar recursos de IA, acompañado de una herramienta de línea de comandos, ctxpm. Organiza el contexto y las capacidades que usa una IA igual que ya organizas el código del proyecto.

Los gestores de paquetes clásicos esperan que escribas comandos para instalar, actualizar y validar. CTXPM sigue un enfoque AI-first. Las reglas del protocolo y la lógica de funcionamiento se inyectan a través de los documentos de entrada de los agentes, y junto con skills integrados y herramientas de CLI permiten que los agentes revisen, actualicen, validen y ordenen recursos mientras programan, revisan y depuran con normalidad. No tienes que aprenderte flags de subcomandos. El agente lee el protocolo, llama a las herramientas y te pregunta cuando hace falta una decisión.

Primero el protocolo, luego la herramienta

CTXPM no te pide reescribir tus skills, rules o prompts existentes, ni ata el proyecto a un único agente. Primero resuelve preguntas con las que tropieza cualquier proyecto real:

• ¿Qué recursos de IA contiene el proyecto?
• ¿Son externos o los mantiene el propio proyecto?
• ¿Dónde están y deben estar bajo control de versiones?
• ¿Desde qué punto de entrada debe leerlos cada agente?
• ¿Cómo se instalan, validan, migran y actualizan?

Esos acuerdos quedan por escrito en el manifiesto ctxpm.yaml, en la estructura de la carpeta .ctxpm/ y en los documentos de entrada para agentes en la raíz del proyecto. La CLI hace más fiables la instalación, la detección y la validación, pero el protocolo no depende de ella. Donde la herramienta no puede ejecutarse, una IA puede entender igualmente el proyecto a partir del manifiesto y los directorios.

Dos tipos de propiedad

Solo existen dos términos de propiedad: dependency y package.

Una dependency es un recurso de IA externo que el proyecto consume. Puede venir de un repositorio Git, de un registro OCI, de una ruta de archivo o de otro sitio. Normalmente no se hace commit de todo su contenido, pero ctxpm.yaml registra el origen, la ruta y una versión estable, de forma muy parecida a las dependencias de terceros en el código de una aplicación.

Un package es algo que el proyecto cuida por su cuenta. Está ligado a la lógica de negocio, la estructura del código o la forma de trabajar del proyecto, así que se hace commit de él, se revisa junto al código fuente y se edita cada vez que el proyecto cambia.

La propiedad es independiente del tipo. Cualquiera de los dos puede ser un skill, rule, spec, prompt, memory o mcp. Un skill de commits importado de GitHub es dependency más skill. Un flujo de publicación propio de un repositorio es package más skill. Los límites del propio proyecto para editar código fuente podrían ser package más rule. Así quedan separados quién mantiene un recurso y a quién preguntar cuando se rompe.

Qué contiene el directorio

Un proyecto que adopta CTXPM suele tener ctxpm.yaml como manifiesto de recursos. Los recursos externos instalados van a .ctxpm/dependencies/, que normalmente figura en .gitignore. Los recursos que mantiene el proyecto van a .ctxpm/packages/, que suele estar bajo control de versiones.

.ctxpm/AGENTS.md es la fuente compartida de los archivos de entrada de los agentes. Según los perfiles de agente activados, la raíz puede recibir copias generadas llamadas AGENTS.md, CLAUDE.md, GEMINI.md o lo que espere cada agente, y todas apuntan al mismo texto. Las reglas se mantienen una sola vez, mientras los archivos de entrada se adaptan a las convenciones de cada agente.

El documento de entrada también le dice a la IA cómo descubrir las cosas. Empezar por el manifiesto, pasar a los packages propios del proyecto, luego a las dependencies externas, y recurrir a memory solo cuando una tarea necesita historial. El contexto no se llena de todos los archivos desde el principio. Eso es lo que hace que el diseño esté dirigido por la IA: el protocolo es una guía de operación y no una configuración estática. El agente lee los recursos por prioridad, decide qué reglas se aplican a la tarea en curso y ejecuta comprobaciones y mantenimiento en los momentos adecuados, de modo que los desarrolladores no tienen que dejar de programar para hacerlo a mano.

El repositorio como ejemplo de sí mismo

El propio repo del proyecto se rige por estas reglas. El propio ctxpm y un skill externo git-commit cuentan como dependencias externas. El flujo de publicación que solo sirve a este repo es package más skill. Un recordatorio de no mezclar el código fuente del producto con los recursos gestionados del propio repositorio es package más rule. Un manifiesto simplificado tiene este aspecto:

version: 1.0

project:
  name: Bear.CTXPM

agents:
  - generic
  - claude-code

dependencies:
  - name: ctxpm
    type: skill
    path: .ctxpm/dependencies/skills/ctxpm
    source:
      type: git
      url: https://github.com/gBearBest/Bear.CTXPM

packages:
  - name: ctxpm-release
    type: skill
    path: .ctxpm/packages/skills/ctxpm-release

  - name: ctxpm-source-boundary
    type: rule
    path: .ctxpm/packages/rules/ctxpm-source-boundary.md

El propósito del manifiesto es dejar las responsabilidades por escrito. Una IA que entre más tarde en el repo puede saber qué contenido sigue al upstream, de qué contenido responde el proyecto y qué reglas leer antes de tocar el código fuente.

De la instalación puntual al mantenimiento a cargo de la IA

Los gestores de paquetes corrientes te obligan a recordar comandos, consultar documentación y lanzar comprobaciones tú mismo. CTXPM convierte esos pasos en un protocolo que una IA puede seguir. Puedes ejecutar los comandos a mano o pasárselos al agente. Una vez que un proyecto ha adoptado el protocolo, los agentes, durante el trabajo rutinario:

• encuentran recursos de IA que aún no están gestionados y preguntan si migrarlos
• buscan actualizaciones de las dependencias externas en momentos sensatos
• confirman que el manifiesto coincide con los directorios reales y reparan automáticamente los enlaces simbólicos de entrada
• te preguntan cuando hay recursos en conflicto o la propiedad no está clara

La IA no ejecuta scripts fijos. Entiende los límites semánticos del protocolo y juzga qué hacer, cuándo y si debe confirmar antes. detect y migrate se ocupan de los recursos heredados mediante un escaneo de solo lectura seguido de tu confirmación sobre qué mover. check-updates y update también están separados a propósito: primero descubrir e informar de los cambios, actualizar después de confirmar.

Para los recursos Git externos habituales, CTXPM registra el commit en el que cambió por última vez la ruta del recurso, no necesariamente el HEAD más reciente del repositorio. Si en un repositorio grande solo cambian otros directorios, un skill dependiente no mostrará una actualización falsa, ya que la versión coincide con la raíz del recurso realmente instalado.

Reparto del trabajo

El protocolo va primero porque un proyecto no puede contar con que haya un binario disponible para que una IA entienda su entorno. Los documentos de entrada le dicen a la IA dónde se guardan los recursos, cuáles están gestionados y cuáles dispersos, dónde están los límites de las dependencias externas y cuándo revisarlas, qué reglas leer antes de una edición y qué manifiestos sincronizar después, y si preguntar o ignorar cuando la propiedad no está clara.

Los pasos fijos encajan en la CLI: crear directorios, reparar enlaces simbólicos, instalar dependencias, calcular versiones, encontrar recursos sin gestionar y validar manifiestos. Las decisiones de criterio corresponden a la IA: decidir a quién pertenece un recurso, explicar riesgos, elegir si pedir confirmación y resolver conflictos de migración. Así, el protocolo fija las reglas, la CLI mantiene estables los pasos repetibles y la IA se ocupa de todo lo que requiere interpretación. Tú te quedas en la capa de decisión.

En la práctica, la IA escanea el proyecto en busca de recursos sin gestionar, lee ctxpm.yaml para conocer propiedad y dependencias, comprueba actualizaciones del upstream, arregla los enlaces simbólicos de entrada y carga los recursos por prioridad para ahorrar contexto. Tú decides si los recursos dispersos pasan a ser paquetes o se marcan como dependencias, si actualizar cuando aparece una versión nueva y qué regla gana cuando dos chocan. Es distinto de npm install, donde recuerdas el comando y lo lanzas. Aquí el agente vigila el estado del proyecto en segundo plano mientras programas, revisas y depuras, y solo habla cuando necesita una decisión.

A quién le sirve

Una demo de IA puntual probablemente no lo necesite. Los proyectos de larga duración, en cambio, suelen toparse con estas situaciones:

• varios agentes tienen que leer un mismo conjunto de reglas del proyecto
• los equipos quieren skills compartidos sin copiarlos en cada repositorio
• los prompts, specs y memories propios del proyecto necesitan revisarse junto al código fuente
• los recursos externos necesitan orígenes, versiones y límites de actualización conocidos
• los archivos de IA antiguos y dispersos necesitan un inventario antes de migrar

CTXPM no escribirá tus prompts ni opina sobre qué agente es más listo. Aclara dónde deben estar los recursos, quién es su dueño y cuánto tiempo viven, para que los flujos de trabajo con IA puedan mantenerse junto con el proyecto.

Cómo empezar

Dale a tu agente esta instrucción:

Sigue la guía de https://raw.githubusercontent.com/gBearBest/Bear.CTXPM/latest/INSTALL.md para inspeccionar este proyecto, configurarlo y reestructurarlo de modo que los recursos y dependencias de IA se gestionen mediante Bear.CTXPM.

El agente identifica qué agentes y recursos existentes usa el proyecto, prepara una CLI local del proyecto y crea los directorios y el manifiesto. Si surgen dudas de propiedad o migración, se detiene y pregunta. A partir de ahí, el trabajo normal dispara el mantenimiento en segundo plano: encontrar recursos dispersos y preguntar si gestionarlos, informar de actualizaciones de dependencias y esperar aprobación, reparar enlaces simbólicos y leer el protocolo para decidir qué cargar.

Si tu proyecto ya tiene rules, skills, prompts o memories, fijar límites pronto te ahorra limpieza más adelante. En ese paso se centra CTXPM: darle al contexto existente un hogar y un responsable conocido. El repositorio está en https://github.com/gBearBest/Bear.CTXPM