open-knowledge

OpenKnowledge — guía para el agente

OpenKnowledge (OK) es una plataforma de colaboración markdown-CRDT expuesta a través de MCP. Este skill es la fuente única de guía para el agente OK. Cada regla a continuación es OBLIGATORIA a menos que se indique lo contrario. La profundidad reside en references/*.md — un nivel de profundidad; carga una referencia cuando surja su tarea.

La versión del skill sigue a @inkeep/open-knowledge-server. cat ~/.ok/skill-state.yml muestra lo que está instalado. ok seed necesita @inkeep/open-knowledge >= 0.4.0; si falla con unknown command, ejecuta npm install -g @inkeep/open-knowledge.

Configuración (¿aún no conectado?). Si las herramientas mcp__open-knowledge__* no están disponibles en tu cliente, este proyecto no está conectado en esta máquina — consulta references/setup.md para la escalera (aprobar .mcp.json → ok start CLI → aplicación de escritorio opcional) y la guía de inicio rápido canónica.

Resumen — el 90% de los casos

1. Lecturas: exec("cat …") para un documento, exec("ls -A …") para un directorio (valores predeterminados de carpeta + menú de plantillas), exec("grep …") para búsqueda literal, search para recuperación clasificada. Read / Grep nativo solo en código fuente (.ts / .py / …), nunca en .md / .mdx dentro del alcance.
2. Escrituras: write({ document: { path, content } }) para un documento nuevo o reemplazo completo; edit({ document: { path, find, replace } }) para buscar y reemplazar en el cuerpo; edit({ document: { path, frontmatter } }) para un parche de fusión en el frontmatter (null elimina una clave). delete({ document }) elimina, move({ from, to }) mueve/renombra. La búsqueda y reemplazo en el cuerpo es solo para el cuerpo. Pasa un summary de una línea (≤80 caracteres, resultado visible para el usuario) en cada escritura de contenido.
3. Vista previa: cada respuesta de lectura/escritura lleva un previewUrl solo de ruta (/#/<doc>, sin host:puerto). Abre el navegador una vez al inicio de la sesión. No uses preview_screenshot para confirmar ediciones — la respuesta de la herramienta es la confirmación. Contrato completo multi-host: references/preview.md.
4. Guías de flujo de trabajo: workflow({ kind: 'ingest' | 'research' | 'consolidate' | 'discover' }) devuelve una guía de procedimientos, no datos. Úsalo cuando el trabajo se ajuste a la capa.
5. Preguntas directas: una pregunta comercial simple ("¿qué clientes…", "¿qué decidimos sobre…") se dirige a search / exec + una respuesta de chat citada — no se necesita la palabra clave "research". Persiste solo cuando sea duradero + multi-documento + no cubierto ya, y ofrece primero. Consulta references/corpus-qa.md.
6. Crear o mejorar un skill ("escribe/haz un skill", "mejora este skill", "convierte esto en un skill"): DETENTE e invoca el skill open-knowledge-write-skill — él posee el alcance de la elección (proyecto vs global), el contrato de SKILL.md, la evaluación y la instalación; no improvises desde este skill. Crea a través del destino skill (write({ skill })), nunca un documento .ok/skills/… sin procesar. Nunca leas, diff o edites las proyecciones instaladas bajo .claude/skills/ · .cursor/skills/ · .codex/skills/ · .opencode/skills/ · .agents/skills/ — install las genera y las sobrescribe en la siguiente sincronización; NO son la fuente de verdad.

Índice de herramientas — 19 herramientas (enrutador; las descripciones de herramientas MCP llevan el contrato completo de cada herramienta)

• Lecturas — exec (principal; cat/ls/grep/find/head/tail/wc/sort/uniq/cut de solo lectura + enriquecimiento de frontmatter/enlaces de retroceso/historial; un comando o un pipe, no un shell), search (BM25 clasificado + actualidad), history (versiones de un documento), links (kind: backlinks|forward|dead|orphans|hubs|suggest, o un array para una auditoría en una sola llamada), skills (encontrar + leer skills: omite name para LISTAR cada skill en Proyecto + Global, pasa name para LEER uno — se aborda por name+scope, NUNCA por ruta), config (configuración resuelta), palette (formularios de creación nativos de markdown + iniciadores de html preview + tokens de tema; palette({ components }) para esquemas JSX), preview_url (URL de vista previa del navegador bajo demanda), share_link (enlace para compartir basado en GitHub; solo lectura, error cuando no hay remoto GitHub).
• Escrituras — cuatro verbos CRUD nativos, polimórficos sobre document / folder / template / skill / asset (pasa EXACTAMENTE UN destino, anidado bajo su clave de dirección): write (crear/sobrescribir; write({ skill: { name, description, body, scope? } }) crea un skill → .ok/skills/<name>/SKILL.md, un Borrador hasta install), edit (buscar y reemplazar en el cuerpo O parche de fusión en el frontmatter; sin asset), delete (eliminar), move (mover/renombrar, reescribe referentes; un skill también toma scope/toScope para mover Proyecto↔Global — el historial se reinicia, se vuelve a install). La salida refleja la clave del destino de entrada; el sobre de vista previa (previewUrl, warning) permanece en el nivel superior. Más install (el paso de Borrador → Instalado para un skill — lo proyecta en tus editores; ejecuta después de write({ skill })), checkpoint (versión nombrada) y restore_version (reversión). El frontmatter de una carpeta es de forma abierta y solo para sí misma (NO se propaga); las plantillas son con lo que comienzan los nuevos documentos. ¿Creando o mejorando un skill? invoca open-knowledge-write-skill (Resumen #6), no improvises.
• Conflictos — conflicts (kind: list|content), resolve_conflict (escribe una resolución + confirma; destructivo). Consulta references/conflict-resolution.md.
• Flujo de trabajo — workflow (kind: ingest|research|consolidate|discover; guías de procedimientos, no datos). Consulta references/workflow-guides.md.

Autocorrección en caso de mal uso: las restricciones que JSON Schema no puede expresar ("exactamente un destino", "find necesita un replace", cuerpo-XOR-frontmatter) devuelven isError: true con una forma correctiva de una línea. Léela y vuelve a intentar con esa forma; no adivines.

Herramientas NO en OK MCP (las de tu host): preview_start, preview_screenshot, WebFetch, WebSearch, Read / Grep / Glob / Edit nativos. La regla STOP rige cuáles puedes usar en markdown dentro del alcance.

STOP — herramientas nativas en .md / .mdx dentro del alcance

Enruta cada lectura y escritura de markdown dentro del alcance a través de las herramientas MCP de OK — nunca las herramientas de archivos nativas de tu host. Edit / sed / Write directo nativo en markdown dentro del alcance omite el CRDT y pierde la atribución del agente en el repositorio sombra; las lecturas nativas omiten el frontmatter, los enlaces de retroceso, la actividad del repositorio sombra y el historial de git del proyecto que OK devuelve para cada archivo coincidente. Cuando este espacio de trabajo tenga OpenKnowledge MCP configurado, no uses herramientas de archivos nativas en rutas de markdown dentro del directorio de contenido. La prohibición cubre cada racionalización común:

• Read / Grep / Glob nativo en .md / .mdx dentro del alcance — el caso original.
• Bash ls / Bash find / Bash cat en directorios que contienen markdown dentro del alcance — usa exec("ls -A …") / exec("find … -name '*.md'") / exec("cat …"). El nativo devuelve nombres simples; exec devuelve frontmatter, recuentos de enlaces de retroceso y actividad reciente. -A muestra entradas ocultas (.ok/, .okignore) sin el ruido de ./...
• Patrones de glob que apuntan a markdown (**/*.md, specs/**, reports/**, docs/**) — usa exec con find o exec("ls -A <dir>").
• Enviar al subagente Explore/de propósito general para exploración intensiva de markdown — los subagentes usan herramientas nativas internamente y omiten OK. Haz la exploración de markdown tú mismo a través de exec / search. Los subagentes siguen siendo apropiados para la exploración de código fuente.
• Read / Grep nativo en markdown dentro del alcance dentro de .ok/ — .ok/ está dentro del alcance; trata sus .md / .mdx como cualquier otro archivo KB.
• ls / cat / find en .ok/skills/ para descubrir o leer un skill — .ok/skills/ es estado interno opaco; los skills se abordan por name+scope, no por ruta. Usa la herramienta skills (omite name para listar en Proyecto + Global, pasa name para leer uno); nunca explores rutas .ok/skills/....

Visibilidad de la herramienta MCP — no ver exec NO es la puerta de escape. El cableado MCP varía según el cliente (Claude Code, Cursor, Codex, Windsurf, VS Code). Las etiquetas del servidor están definidas por el usuario; las herramientas pueden no aparecer como símbolos de nivel superior llamados exec. Si OpenKnowledge está registrado como un servidor MCP aquí, enruta las lecturas de markdown a través de su exec / search mediante la invocación MCP documentada de tu cliente (incluyendo cualquier flujo genérico de "llamar a la herramienta MCP"). El registro es la prueba, no la visibilidad del símbolo de nivel superior.

Tu lista de herramientas inicial NO es exhaustiva — ejecuta el descubrimiento de herramientas antes de concluir que falta el MCP. Algunos clientes (notablemente Codex) difieren las herramientas MCP detrás de un paso perezoso tool_search / descubrimiento de herramientas, por lo que mcp__open-knowledge__* está ausente del conjunto de herramientas inicial y solo aparece después de que lo buscas. La ausencia de la lista visible significa "aún no lo he descubierto", NO "no está registrado". Si no ves las herramientas, tu primer movimiento es ejecutar el descubrimiento de herramientas de tu cliente / tool_search para open-knowledge (o exec / search / write) — no infieras la no disponibilidad de la lista inicial.

Puerta de escape. Read / Grep / Glob nativo en .md / .mdx está permitido solo cuando, después de ejecutar el descubrimiento de herramientas (arriba), ningún servidor MCP de OpenKnowledge está registrado para este proyecto, o inmediatamente después de que realmente invocaste una llamada MCP y falló — entonces comienza una oración visible para el usuario con OpenKnowledge MCP no disponible:. "No registrado" es una conclusión a la que solo puedes llegar después de que el descubrimiento de herramientas no encontró nada — nunca solo de la lista inicial. Nunca uses la puerta de escape porque omitiste la ruta MCP de tu cliente, no viste exec como una herramienta de nivel superior, no ejecutaste el descubrimiento de herramientas, o racionalizaste que el skill no era necesario.

Código fuente y archivos que no son markdown (.ts, .py, package.json, …): Read / Grep / Glob nativo siempre.

Lecturas — ejemplos

• Leer un archivo: exec("cat <ruta>.md") — contenido + enriquecimiento completo.
• Listar un directorio: exec("ls -A <dir>") — frontmatter por hijo, recuentos de markdown recursivos, documento más recientemente actualizado por subdirectorio, el propio title/description/tags de la carpeta + templates_available. Prefiere -A sobre ls simple.
• Búsqueda literal: exec("grep -rn <término> <dir> | head -5") — coincidencias + enriquecimiento en los archivos coincidentes.
• Búsqueda clasificada: search({ query }) — aumento de título + BM25 del cuerpo + actualidad; úsalo al elegir el mejor documento, no al listar cada ocurrencia.

Escritura

Llama a write / edit tan pronto como tengas contenido (enruta a través de MCP según la regla STOP).

Persiste incrementalmente — la base de conocimiento ES tu punto de control (OBLIGATORIO). En cualquier tarea de múltiples pasos o larga duración — un barrido de investigación, una síntesis de múltiples fuentes, un lote de documentos — escribe el trabajo completado en la KB a medida que terminas cada unidad: por sección, por fuente, por documento. Nunca mantengas los hallazgos terminados solo en tu contexto esperando una escritura final al final. Un límite de velocidad, un bloqueo o una compactación del contexto a mitad de la tarea descarta todo lo que aún no se ha escrito; el trabajo ya persistido sobrevive, y reanudas leyendo el documento de nuevo. Crea el documento de destino temprano (esqueleto + frontmatter), luego edit cada sección a medida que se consolida.

Pasa un summary en cada escritura de contenido (RECOMENDADO) — una nota de cambio visible para el usuario de una línea (≤80 caracteres) que se convierte en la entrada de la línea de tiempo. Recurre a la estructura visual (Callout, mermaid, tabla, html preview) donde transmita el punto mejor que la prosa; llama a palette mientras redactas. Avisos de escritura, creación de MDX, mecánicas de eliminación/movimiento y creación visual: references/writing.md + references/components-and-visuals.md + references/media-and-assets.md.

Fundamentación — cada afirmación factual necesita una fuente (OBLIGATORIO)

Los documentos de la base de conocimiento son artefactos factuales. Cada afirmación debe ser rastreable, y la fuente debe vivir dentro de la base de conocimiento, no flotar en la web pública.

• La base de conocimiento es la fuente de verdad — bucle cerrado. Las fuentes externas no se citan hacia la web en vivo; se incorporan a través de ingest, luego se citan localmente. Una URL [fuente](https://...) simple dentro de un documento KB no es una cita terminada — es un TODO que dice "esta fuente aún necesita ser ingerida". La cadena solo funciona si cada hoja es un documento local.
• Cada afirmación factual OBLIGATORIAMENTE debe citar su fuente en el punto de la afirmación. Sin especulación sin fuente.
• Fuentes web para documentos KB → obtén la página (WebFetch / WebSearch del host), luego ingest como un documento local, luego cita la ruta local: [nombre de la fuente](./ruta/a/la/fuente.md) (el documento local lleva la URL en source_url:). [fuente](URL) en línea es una ayuda de chat, no una de KB.
• Recuentos auto-obtenidos. Cuando TÚ obtuviste una URL para fundamentar una afirmación que termina en la KB, esa obtención desencadena ingest exactamente como un recurso compartido de usuario — no lo degrades a una cita de URL en línea porque la obtención fue iniciada por el agente.
• Referencias cruzadas internas → enlace markdown estándar al documento OK con la afirmación autorizada; ese documento debe citar sus propias fuentes (las cadenas terminan en documentos locales preservados).
• Si no tienes evidencia: ejecuta una búsqueda web e ingest, O marca en línea (TODO: necesita fuente), O no escribas la afirmación. NO fabriques. La especulación sin fuente se pudre en conocimiento tribal no rastreable.

Enlaces — enlaces markdown estándar (OBLIGATORIO)

Enlaza cada frase nominal que nombre otro documento — [texto](./ruta/relativa.md) — y enlaza liberalmente. Cada enlace debe resolver a un documento que exista para cuando termines (una referencia directa del mismo pase que creas más tarde en el pase está bien; para uno que genuinamente no existirá, deja la mención como prosa simple + una tarea rastreada). Nunca uses comillas invertidas en un enlace (`[texto](./foo.md)` es un error) y nunca uses <a> HTML. Lee brokenLinks en cada respuesta de write/edit: [] significa que todos los enlaces resuelven; una lista poblada nombra cada href roto + reason (no-such-doc / no-such-file / unresolvable) — arréglalos en un edit de seguimiento. links({ kind: "dead" }) es la auditoría de estado final autorizada (el subrayado rojo del editor es tolerante con los slugs y miente, así que confía en la herramienta). Las fuentes web externas NO son enlaces en línea del cuerpo (consulta Fundamentación). Conjunto completo de reglas + la nota heredada de [[Page]]: references/linking.md.

Carpetas, frontmatter, plantillas

Cada .md / .mdx necesita frontmatter YAML — title + description obligatorios, tags recomendado. Dos mecanismos de carpeta opt-in, anidados: frontmatter de carpeta (<carpeta>/.ok/frontmatter.yml — propiedades de forma abierta de la propia carpeta; solo para sí misma, NO se propaga

…

[truncado para traducción]