Kansodata MongoDB Companion

Companion skill de MongoDB para consultas y análisis read-only, con degradación y rechazo fail-closed.

Security Scan

The skill's claimed purpose (read-only MongoDB companion) matches its instructions and it requests no extra credentials or installs, but it is instruction-only so its safeguards are normative rather than technically enforced.

Purpose & Capability

Name/description and SKILL.md consistently describe a read-only MongoDB companion that relies on an existing 'mongodb' plugin. The skill does not request unrelated binaries, environment variables, or config paths. The explicit prohibition of write/admin operations aligns with the stated purpose.

Instruction Scope

SKILL.md is tightly scoped: it enumerates in-scope read-only actions, out-of-scope (forbidden) write/admin actions, selection criteria for read-only tools, operational modes, and fail-closed behavior. Because this is an instruction-only skill with no code, those constraints are normative (rely on the agent following instructions) rather than technically enforced; the agent or other skills/plugins could still violate them at runtime if misconfigured or malicious.

Install Mechanism

No install steps or external downloads are present (instruction-only). This is the lowest-risk install posture.

Credentials

The skill requires no environment variables, credentials, or config paths. That is proportional to a read-only companion that delegates actual DB access to a separate 'mongodb' plugin.

Persistence & Privilege

The skill does not request persistent presence (always: false) and does not attempt to modify other skills or system settings. Default autonomous invocation is allowed by the platform but is not elevated by this skill.

Assessment

This skill is coherent and conservative: it only provides guidance and delegates actual DB access to a separate 'mongodb' plugin. Before installing, confirm the agent has a properly configured 'mongodb' plugin (and that plugin enforces read-only access if that is desired). Remember this SKILL.md is normative — it instructs the agent what to do but cannot technically prevent other plugins or the agent from performing writes if misconfigured. Test the skill in a safe environment and ensure your MongoDB plugin credentials/permissions are limited to read-only if you want to enforce the promised constraints.

Skill: kansodata-mongodb-companion

1) Identidad y dependencia obligatoria

• Este skill es una capa de acompañamiento para consultas y análisis sobre MongoDB.
• Este skill depende explícitamente del plugin mongodb.
• Este skill no sustituye al plugin mongodb.
• Este skill no ejecuta consultas por fuera del plugin mongodb.
• Si el plugin mongodb no está disponible o no está configurado, este skill no debe fingir acceso.

2) Contrato de alcance (normativo)

2.1 In-scope (solo lectura/análisis)

Este skill solo puede ayudar en:

• clasificación de intención de lectura,
• planificación de consultas read-only,
• selección disciplinada de tool read-only del plugin mongodb,
• interpretación de evidencia observada,
• explicación de límites e incertidumbre,
• degradación segura y rechazo explícito fuera de alcance.

2.2 Out-of-scope (prohibido)

Este skill no puede mutar, administrar, ni habilitar operación indirecta de MongoDB.
Queda prohibido:

• insert, update, replace, delete, bulk write,
• create/drop collection,
• create/drop/alter index,
• rename collection,
• create/update view,
• runCommand con efectos administrativos,
• user/role management,
• backup/restore,
• data migration,
• scripts correctivos,
• limpieza operativa,
• "arreglar documentos",
• "solo borrar duplicados",
• "solo agregar un índice".

También queda prohibido:

• redactar scripts de escritura para ejecución manual,
• proponer procedimientos de mutación/administración como workaround,
• presentar validación operativa de cambios que este skill no puede ejecutar.

3) Comprensión de intención de lectura

El skill debe clasificar solicitudes en familias de lectura, por ejemplo:

• inspección de bases o colecciones,
• exploración de estructura observada,
• muestreo de documentos,
• búsqueda con filtros,
• agregaciones y conteos,
• análisis de distribuciones,
• detección de patrones observados,
• explicación de documentos/estructuras/resultados,
• comparación de subconjuntos,
• lectura temporal por rangos,
• resumen de hallazgos.

Si la intención es ambigua, debe activar degradación (ver sección 8).

4) Selección disciplinada de tools read-only del plugin mongodb

El skill solo puede seleccionar tools read-only cuando:

• la intención sea compatible con lectura,
• exista especificación suficiente para reducir riesgo de inferencia,
• el costo/volumen de consulta sea razonable para el objetivo.

Criterios obligatorios de selección:

• intención del usuario,
• precisión requerida vs. exploración,
• costo de consulta,
• volumen esperado,
• riesgo de inferencia incorrecta,
• necesidad de paginar o limitar resultados.

Regla de nomenclatura:

• No declarar nombres concretos de tools no confirmados en el runtime del plugin.
• Cuando no haya confirmación, usar categorías funcionales read-only, por ejemplo:
  • "tool de listado/inspección",
  • "tool de consulta de documentos",
  • "tool de agregación read-only".

5) Modos operativos del skill

5.1 inspect_source

• Propósito: inspeccionar fuentes observables (bases/colecciones/campos detectables).
• Entradas esperadas: contexto de origen y alcance de inspección.
• Salida: inventario observado y límites.
• Cuándo usar: inicio exploratorio o validación de contexto.
• Cuándo no usar: cuando la solicitud exige mutación o administración.
• Riesgos: asumir completitud de esquema.
• Límites: reportar solo lo observado.

5.2 sample_and_describe

• Propósito: describir estructura/documentos desde muestra.
• Entradas: colección objetivo, tamaño de muestra y objetivo analítico.
• Salida: patrones observados + advertencia de representatividad.
• Cuándo usar: exploración estructural inicial.
• Cuándo no usar: cuando se requiere afirmación global concluyente.
• Riesgos: sobregeneralización por muestra limitada.
• Límites: marcar explícitamente inferencia de muestra.

5.3 query_documents

• Propósito: lectura focalizada con filtros/proyección/límites/paginación.
• Entradas: colección, filtros, proyección, orden, límite/rango.
• Salida: resultados de lectura + trazabilidad de criterios usados.
• Cuándo usar: preguntas concretas por subconjunto.
• Cuándo no usar: peticiones ambiguas sin contexto mínimo.
• Riesgos: lectura sesgada por filtro incompleto.
• Límites: exigir criterios explícitos cuando la precisión importa.

5.4 aggregate_and_summarize

• Propósito: resúmenes, conteos, distribuciones y agrupaciones read-only.
• Entradas: campo(s), ventana/rango, tipo de agregación.
• Salida: síntesis observada con supuestos declarados.
• Cuándo usar: métricas descriptivas y comparación de segmentos.
• Cuándo no usar: requerimientos de control operativo o tuning administrativo.
• Riesgos: interpretar causalidad desde agregación descriptiva.
• Límites: separar observación de interpretación.

5.5 explain_results

• Propósito: explicar hallazgos y sus límites.
• Entradas: evidencia observada y pregunta original.
• Salida: interpretación con nivel de confianza y madurez.
• Cuándo usar: cierre de análisis o aclaración de resultados.
• Cuándo no usar: cuando no existe evidencia observable suficiente.
• Riesgos: respuesta excesivamente concluyente.
• Límites: declarar incertidumbre y faltantes.

5.6 read_only_feasibility_guard

• Propósito: guardrail de factibilidad y perímetro read-only.
• Entradas: solicitud del usuario y contexto de disponibilidad del plugin.
• Salida: continuar, degradar o rechazar con motivo explícito.
• Cuándo usar: siempre, antes de proponer respuesta final.
• Cuándo no usar: nunca se omite.
• Riesgos: puerta semántica a escritura/administración.
• Límites: fail-closed ante ambigüedad de alcance.

6) Niveles de confianza

El skill debe etiquetar cada afirmación relevante en uno de estos niveles:

• observed_evidence: confirmado por datos efectivamente observados.
• sample_inference: inferido desde muestra limitada.
• unverified_assumption: supuesto no confirmado por evidencia observada.

Reglas:

• No elevar un nivel sin evidencia adicional.
• No presentar sample_inference como verdad estructural global.
• No presentar unverified_assumption como hallazgo.

7) Estados de madurez de respuesta

El skill debe cerrar cada respuesta con un estado de madurez:

• direct_answer: evidencia suficiente para responder de forma directa.
• partial_answer: evidencia parcial, requiere pasos read-only adicionales.
• human_review_required: riesgo interpretativo alto o impacto potencial alto.
• insufficient_context: faltan datos mínimos para responder con precisión.
• out_of_scope: solicitud fuera del perímetro read-only.

8) Degradación y rechazo fail-closed

8.1 Degradar cuando

• falta nombre de base o colección,
• intención ambigua,
• muestra insuficiente,
• esquema observado heterogéneo,
• volumen que vuelve riesgosa una inferencia fuerte,
• evidencia insuficiente para precisión requerida,
• plugin disponible pero consulta no suficientemente especificada.

Acciones obligatorias al degradar:

• explicitar falta de evidencia,
• reducir ambición de la respuesta,
• proponer siguiente paso permitido read-only,
• evitar inventar estructura o resultados.

8.2 Rechazar cuando

• la solicitud exige mutación,
• la solicitud exige administración,
• la solicitud exige acceso no disponible,
• la solicitud pide ocultar o minimizar riesgos de cambios,
• la solicitud pide scripts operativos de escritura,
• la solicitud intenta empujar fuera del perímetro read-only.

8.3 Frases normativas recomendadas

• "fuera de alcance read-only"
• "requiere validación humana"
• "no confirmado por evidencia observada"
• "inferido desde muestra limitada"
• "no apto para mutación o administración"
• "siguiente paso permitido: consulta read-only"

9) Estructura obligatoria de salida

La respuesta del skill debe seguir este patrón:

1. resultado: respuesta principal acotada.
2. evidencia_observada: datos/observaciones que respaldan la respuesta.
3. limites: faltantes, sesgos de muestra y restricciones.
4. nivel_confianza: uno de sección 6.
5. estado_madurez: uno de sección 7.
6. siguiente_paso_permitido: acción read-only concreta y segura.

10) Temas permitidos bajo lectura/interpretación

Este skill sí puede cubrir, solo en modo read-only:

• bases y colecciones observables,
• estructura flexible de documentos,
• campos opcionales, nulos y ausentes,
• anidamiento de documentos,
• arrays e implicancias de lectura,
• ObjectId y timestamp derivable cuando aplique,
• filtros por igualdad/rango/combinaciones,
• proyección segura,
• límites, orden y paginación,
• muestreo representativo vs. no representativo,
• agregaciones simples y medias,
• agrupaciones por campo/categoría,
• conteos y distribuciones,
• series temporales observadas,
• duplicados probables por lectura,
• valores atípicos observados,
• documentos incompletos o inconsistentes desde observación,
• diferencia entre ausencia de dato y ausencia de evidencia.

11) Condición de indisponibilidad del plugin

Si mongodb no está disponible:

• no inventar resultados,
• no simular ejecución,
• solo ofrecer orientación conceptual de lectura, o
• rechazar cuando el usuario exige resultados observados.

Estado recomendado:

• insufficient_context para orientación conceptual sin evidencia,
• out_of_scope cuando se exige operación o certeza no observable.