> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fhiron.cl/llms.txt
> Use this file to discover all available pages before exploring further.

# Skill CL Core (agent behavior)

> Operating contract, playbooks y referencias canónicas que el MCP entrega al agente desde initialize.

## Qué es

El MCP no solo expone tools y resources, también entrega **comportamiento** al agente. Desde `initialize`, el servidor devuelve un campo `instructions` (spec MCP 2024-11-05) con el operating contract que el cliente inyecta como system-level guidance del LLM. Adicionalmente, expone 17 recursos descubribles bajo el URI `agent-skill://fhiron-cl/...` con el detalle profundo: playbooks por intent, referencia canónica de perfiles, catálogo de códigos de error y ejemplos reproducibles end-to-end.

Todo viene de fábrica al conectar el MCP. No requiere copiar archivos al filesystem ni instalar plugins extra. Funciona idéntico en cualquier cliente MCP-compatible.

## Por qué importa

Los LLM tienden a equivocarse de tool. Sin guidance, suelen llamar `fhiron_validate` (1 crédito) cuando `fhiron_lint` (gratis) habría detectado el problema. O presentan errores en formato libre, sin citar el perfil que falla. O inventan terminología cuando el catálogo no tiene match.

La skill cierra ese hueco: el LLM arranca sabiendo qué tool usar para qué intent, cómo presentar issues, cuándo aplicar `quickFix` automático, y cuál es la política de canonical-only. La diferencia se nota desde el primer turn.

## Cómo se activa

Cualquier cliente MCP-compatible que conecte el servidor lee `instructions` automáticamente al iniciar la sesión:

| Cliente                                | Comportamiento al conectar                                                    |
| -------------------------------------- | ----------------------------------------------------------------------------- |
| Claude Code                            | Inyecta `instructions` como system guidance + lista resources en `/resources` |
| Cursor                                 | Inyecta `instructions` como system + resources en sidebar MCP                 |
| Continue.dev                           | Idem + resources/prompts listables vía `@`                                    |
| Gemini Code Assist                     | Inyecta `instructions`; resources via comando                                 |
| Grok-Studio                            | Idem (MCP support desde Q1 2026)                                              |
| ChatGPT (Custom GPT con MCP connector) | `instructions` como context inicial                                           |
| JetBrains AI                           | Idem                                                                          |

Para instalar el MCP:

```bash theme={null}
npx @fhiron/mcp-connector init
```

El wizard registra el servidor en el config del cliente y obtiene una API key del plan gratis (1.000 validaciones/mes).

## Operating contract (5 reglas que rigen al agente)

1. **Canonical-only.** Toda URL citada viene de `hl7.fhir.cl.clcore`, `hl7.fhir.r4.core`, `hl7.terminology.r4` o `hl7.fhir.cl.minsal.eis`. Si algo no está en estos paquetes, el agente lo dice explícito y no inventa.
2. **Errores en español neutro chileno** (tuteo, sin voseo). Los nombres técnicos quedan en inglés. Cada issue cita el `StructureDefinition.url` que falla.
3. **`quickFix` antes que explicación.** Si el issue trae fix mecánico, el agente propone aplicarlo antes de explicar la causa.
4. **Selección de tools consciente de costos.** Tools gratis offline primero; escala a tools de pago solo cuando el resultado offline no alcanza. Antes de cada llamada con costo, anuncia el costo.
5. **Disciplina HL7®/FHIR®.** Primera mención por turn con el símbolo registrado; las siguientes sin. Identificadores técnicos nunca lo llevan.

## Routing por intent

| Lo que dice el desarrollador                | Tools que invoca el agente                 | Costo      |
| ------------------------------------------- | ------------------------------------------ | ---------- |
| *"valida este Patient"* + JSON              | `fhiron_lint` → `fhiron_validate`          | 0–1 cr     |
| *"qué significa `cl-X`"*                    | `fhiron_explain_code` → `fhiron_apply_fix` | 0          |
| *"dame un ejemplo de Encounter chileno"*    | `fhiron_get_example`                       | 0          |
| *"código de comuna X / fármaco Y"*          | `fhiron_search_terminology`                | 0          |
| *"escanea mi endpoint"* + URL pública       | `fhiron_score_endpoint`                    | 0          |
| *"qué cambia entre R4 y CL Core"* + recurso | `fhiron_compare_profiles`                  | 2 cr       |
| Bundle (`"resourceType": "Bundle"`)         | `fhiron_validate_bundle`                   | 1 cr/entry |

## Recursos descubribles (`resources/list`)

El MCP expone 17 documentos bajo `agent-skill://fhiron-cl/` que el agente puede leer bajo demanda:

| Categoría      | URI                                                                            | Para qué                                                       |
| -------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------- |
| Entry point    | `agent-skill://fhiron-cl/SKILL.md`                                             | Decision tree, 5 reglas, handling de inputs no-JSON            |
| Triggers       | `agent-skill://fhiron-cl/triggers.md`                                          | Patrones que activan el comportamiento                         |
| Conventions    | `agent-skill://fhiron-cl/conventions.md`                                       | Style guide y tabla de costos                                  |
| Playbooks (5)  | `agent-skill://fhiron-cl/playbooks/{validate,explore,repair,score,compare}.md` | Orquestación por intent                                        |
| Referencia (3) | `agent-skill://fhiron-cl/reference/{profiles-cl,catalogs,error-codes}.md`      | Perfiles canónicos, catálogos chilenos, diccionario de códigos |
| Ejemplos (6)   | `agent-skill://fhiron-cl/examples/0{1..6}-*.md`                                | Sesiones end-to-end reproducibles                              |

## Ejemplo de turn

**Desarrollador pega:**

```json theme={null}
{
  "resourceType": "Patient",
  "identifier": [{
    "system": "http://www.registrocivil.cl/run",
    "value": "11.111.111-1"
  }],
  "name": [{ "family": "González" }]
}
```

**Agente (con la skill activa):**

> Detecté un `Patient`. Corro `fhiron_lint` primero (offline, gratis).
>
> Encontré 3 issues:
>
> * **`cl-run-01`**: `identifier[0].value` contiene puntos. CL Core CorePacienteCl normaliza el RUN sin puntos: `11111111-1`. `quickFix` disponible.
> * **`cl-narrative-02`**: falta `text.div`. FHIR® R4 dom-6 lo recomienda. `quickFix` agrega narrativa mínima.
> * **`cl-patient-04`**: `gender` ausente. CorePacienteCl lo recomienda (`male` · `female` · `other` · `unknown`). `quickFix` → `"unknown"`; edítalo si conoces el dato.
>
> ¿Aplico los 3 `quickFix` automáticos (offline, gratis) o prefieres revisarlos uno por uno antes?

## Capabilities cubiertas

* 8 perfiles CL Core 1.9.4 (CorePacienteCl, CorePrestadorCl, CoreOrganizacionCl, EncounterCL, CoreDiagnosticoCl, CoreAlergiaIntCl, CoreMedicamentoCl, ImmunizationCL).
* 6 perfiles MISSING (`Procedure`, `MedicationRequest`, `Coverage`, `Observation` laboratorio/signos vitales, `Composition`). La skill aplica recomendaciones sobre R4 base hasta que HL7® Chile los publique.
* 60+ códigos `cl-*` documentados con severity, profile, quickFix.
* Catálogos chilenos: comunas (decreto 817), DEIS, ATC, SNOMED CT, CIE-10, LOINC, CVX, v3-ActCode, CSTipoIdentificador, CSPrevision (MINSAL EIS).

## Versionado

La skill se versiona junto al MCP. Cada release de `@fhiron/mcp-connector` lleva la skill embebida actualizada. Los clientes obtienen actualizaciones con `npm update`.

## Out of scope

HL7® v2, CDA, DICOM. Composición de recursos (el desarrollador escribe el FHIR®; el MCP valida).