El skill de Context Architecture, aplícalo con tu agente

El skill es la especificación, convertida en algo que tu agente corre. Un archivo Markdown. Lo cargas, lo apuntas a un repo, y lee el código como un lector sin memoria, lo audita contra los nueve principios y encuentra las afirmaciones que el repositorio hace sobre sí mismo que no están atadas a un mecanismo que falla cuando dejan de ser ciertas. Después te devuelve el backlog en el orden que arma la guía.

Sin servidor, sin dependencia, sin herramientas especiales. Es un archivo que tu agente lee, que es el principio 05 (Las capacidades son descubribles) aplicado al skill mismo.

Qué hace

• Audita el repo contra los nueve principios y escribe un informe con un veredicto y la evidencia que lo respalda, uno por principio: qué afirmaciones están atadas a un mecanismo y cuáles son solo prosa.
• Encuentra afirmaciones sueltas: docs que citan archivos borrados, nombran módulos renombrados o contradicen el código, y convenciones que viven solo en prosa sin nada que falle cuando se rompen.
• Propone un backlog: cambios del tamaño de un PR ordenados por impacto, cada uno emparejado con el mecanismo (compilador, linter, prueba automatizada, revisión) que falla cuando su afirmación deja de ser cierta.
• Redacta archivos AGENTS.md en las fronteras, con solo lo que no puedes sacar del código.

Aplica desde el primer commit, así un repo puede nacer legible, y también sobre un repo que creció sin diseño, reestructurado en pasos. Hace la misma auditoría en ambos casos.

Instalarlo

Un comando cubre la mayoría de las herramientas. El CLI skills lee el skill desde el repo y lo deja en el agente que tengas:

npx skills add sergioazoc/context-architecture

Te pregunta en qué herramienta instalarlo. Pasa -a <herramienta> para elegir una (por ejemplo -a claude-code), -g para instalarlo en todos tus proyectos, y -y para saltarte las preguntas. Las secciones por herramienta de abajo cubren el camino manual, por si prefieres dejar el archivo tú mismo o tu herramienta no está en su lista.

Claude Code

npx skills add sergioazoc/context-architecture -a claude-code -g

A mano, sin Node: guarda el archivo en una carpeta con el nombre del skill, luego reinicia Claude Code. El nombre de la carpeta es lo que escribes como el comando /context-architecture, así que déjalo exactamente así.

mkdir -p ~/.claude/skills/context-architecture
curl -fsSL https://context-architecture.dev/skill.md -o ~/.claude/skills/context-architecture/SKILL.md

Quita el ~/.claude para una instalación personal; usa .claude/skills/context-architecture/SKILL.md para acotarlo a un solo proyecto.

Cursor

Guárdalo como una regla de proyecto. La extensión .mdc importa, un .md plano en esa carpeta se ignora:

mkdir -p .cursor/rules
curl -fsSL https://context-architecture.dev/skill.md -o .cursor/rules/context-architecture.mdc

El description del frontmatter le dice a Cursor que traiga la regla cuando es relevante.

GitHub Copilot (VS Code)

VS Code lee Agent Skills de forma nativa, el mismo formato SKILL.md. La carpeta debe llamarse como el skill, o Copilot no lo carga:

mkdir -p .github/skills/context-architecture
curl -fsSL https://context-architecture.dev/skill.md -o .github/skills/context-architecture/SKILL.md

En JetBrains, o en un Copilot viejo sin skills, pega el archivo en .github/copilot-instructions.md.

OpenAI Codex

mkdir -p ~/.agents/skills/context-architecture
curl -fsSL https://context-architecture.dev/skill.md -o ~/.agents/skills/context-architecture/SKILL.md

Usa un .agents/skills/context-architecture/SKILL.md local para acotarlo a un repo. Reinicia Codex si no toma el skill.

Otras herramientas

La misma idea: el archivo va donde la herramienta lee sus reglas.

• Windsurf: .windsurf/rules/context-architecture.md. Si Windsurf se queja por el tamaño, apúntalo al archivo en vez de pegar todo.
• Cline: .clinerules/context-architecture.md.
• Zed: agrégalo a tu AGENTS.md, que Zed lee. Un archivo .rules suelto puede tapar uno existente, así que agregarlo al AGENTS.md es más seguro.
• Aider: guárdalo como CONVENTIONS.md, luego corre aider --read CONVENTIONS.md.

Cualquier otro agente

Toma el archivo en crudo y pégalo en las instrucciones de tu herramienta, o apúntala a él:

curl -fsSL https://context-architecture.dev/skill.md

Es autocontenido. Reenuncia la regla y los nueve principios, así que funciona sin vuelta a este sitio.

Usarlo

Carga el skill y apunta tu agente a un repo:

Aplica el skill de Context Architecture a este repositorio.

Escribe primero la auditoría, solo lectura, después el backlog ordenado. Trabájalo un cambio a la vez, cada uno aterrizando con el mecanismo que falla cuando su afirmación deja de ser cierta. Empieza donde te diga: las afirmaciones que son solo prosa, y los AGENTS.md de las fronteras de arriba. Ahí es donde más recuperas por edición.

Mantenerlo al día

Las actualizaciones viajan por la rama por defecto: un cambio le llega a alguien solo cuando se mergea a main y se vuelve a deployar el sitio. Después, cómo lo bajas depende de cómo lo instalaste.

• Plugin de Claude Code (/plugin marketplace add): corre /plugin marketplace update context-architecture. Cada release sube la versión del plugin, así Claude Code ve una versión nueva y la baja. Una versión sin cambios la trata como cacheada y la salta, por eso cada cambio en el skill viaja con un bump de versión.
• CLI skills: vuelve a correr npx skills add sergioazoc/context-architecture. Sobreescribe la copia instalada desde el repo.
• Instalación manual (curl): vuelve a correr el mismo curl ... -o <ruta> con el que instalaste; sobreescribe el archivo. Claude Code toma un archivo ~/.claude/skills/... editado dentro de la sesión, sin reiniciar.

Hacia dónde seguir

• La especificación: la regla, el loop, los tipos de mecanismo y los nueve principios.
• La guía: el mismo trabajo, hecho a mano, paso a paso.
• El glosario: los términos que usa el skill, definidos.