Saltar al contenido principal
Modo · Memoria agéntica

Quickstart — Skill para agentes

GRAIL incluye un skill portable en skills/grail/ que tu agente de programación puede usar directamente. Funciona en cualquier framework que soporte el formato estándar SKILL.md.

Frameworks soportados​

FrameworkRuta de usuarioRuta de proyecto
Claude Code (CLI + claude.ai)~/.claude/skills/grail/<repo>/.claude/skills/grail/
OpenAI Codex~/.agents/skills/grail/<repo>/.agents/skills/grail/
OpenCode y otros con SKILL.mddirectorio de skills del frameworkigual

1. Instalar el skill​

Opción rápida (recomendada)​

El skill está publicado en el catálogo cchia-skills. Instalalo con un solo comando usando el CLI de skills:

npx skills add CAMARA-CHILENA-INTELIGENCIA-ARTIFICIAL/cchia-skills --skill grail

Esto deja el skill en ~/.claude/skills/grail/ y lo deja disponible para Claude Code automáticamente. Para Codex u otros frameworks, apuntá el instalador (o el symlink de abajo) al directorio de skills correspondiente.

Opción manual (clonar + symlink)​

Ideal para desarrollar el skill: clonás GRAIL y enlazás la carpeta, así cuando hacés git pull el skill se actualiza solo.

git clone git@github.com:CAMARA-CHILENA-INTELIGENCIA-ARTIFICIAL/GRAIL.git
cd GRAIL

# Claude Code
mkdir -p ~/.claude/skills
ln -s "$(pwd)/skills/grail" ~/.claude/skills/grail

# Codex
mkdir -p ~/.agents/skills
ln -s "$(pwd)/skills/grail" ~/.agents/skills/grail

# Scope de proyecto (skill compartido con tu repo)
cd /ruta/a/tu/repo
mkdir -p .claude/skills
ln -s "$(realpath /ruta/a/GRAIL/skills/grail)" .claude/skills/grail

Si tu sistema no soporta symlinks (algunos Windows), reemplaza ln -s por cp -R.

2. Setup en la primera sesión​

La primera vez que tu agente use el skill, scripts/setup.sh instala GRAIL vía pip. Es idempotente — seguro de llamar siempre.

bash ~/.claude/skills/grail/scripts/setup.sh
# → {"ok": true, "status": "installed", "grail_version": "0.1.0"}

Verifica con:

python ~/.claude/skills/grail/scripts/env_check.py

3. Qué hace el skill por ti​

El skill expone primitivas como scripts CLI que devuelven JSON. Tu agente las invoca según el contexto de la conversación.

Primitivas de descubrimiento​

python scripts/list_grail_projects.py     # ¿qué proyectos existen?
python scripts/status.py --project mi-mem # ¿modo? ¿conteos? ¿último indexado?

Primitivas de memoria (modo memory)​

python scripts/memory/add_observation.py --project mi-mem \
  --title "..." --content "..." --category "..." \
  --tag decision \
  --entities '[...]' \
  --relationships '[...]'

python scripts/memory/recall.py --project mi-mem --since 7d --tag decision

python scripts/memory/consolidate.py     --project mi-mem
python scripts/memory/list_proposals.py  --project mi-mem
python scripts/memory/apply_proposal.py  --project mi-mem --accept <id>

Primitivas de KB (modo knowledge_base)​

python scripts/index.py        --project mi-kb
python scripts/query.py        --project mi-kb --question "..." --mode cascade
python scripts/append.py       --project mi-kb --file nuevo.pdf
python scripts/edit.py         --project mi-kb --name x.md --src /tmp/y.md
python scripts/delete.py       --project mi-kb --files antiguo.txt

Todas devuelven el mismo envoltorio JSON:

{
  "ok": true,
  "data": { /* el resultado */ },
  "warnings": [],
  "next_steps": []
}

Cuando algo falla:

{
  "ok": false,
  "error": "Descripción legible para el agente",
  "next_steps": ["Sugerencias accionables"]
}

4. Variables de entorno​

El skill necesita las API keys que use tu grail.yaml. Si vas a usar modo memoria sin embeddings, no necesitas ninguna llave — recall funciona offline.

Si vas a usar cascade / local / global / agent / document, sí necesitas la key del proveedor LLM de tu config (común: OPENAI_API_KEY, DEEPINFRA_API_KEY, ANTHROPIC_API_KEY).

5. Probarlo en el agente​

Una vez instalado, tu agente debería poder responder a frases como:

  • "Recuérdame que decidimos usar Postgres en el proyecto Acme."
  • "¿Qué decisiones tomé la semana pasada?"
  • "Lista mis proyectos de GRAIL."
  • "Indexa estos PDFs en un nuevo proyecto llamado papers."

El skill ya trae el lenguaje de activación pre-cargado en SKILL.md para que el agente reconozca cuándo usarlo.

Cómo se actualiza​

Si instalaste con npx skills add, volvé a correr el mismo comando para traer la última versión:

npx skills add CAMARA-CHILENA-INTELIGENCIA-ARTIFICIAL/cchia-skills --skill grail

Si instalaste por symlink:

cd /ruta/a/GRAIL && git pull

El skill ya está actualizado — no hay nada más que hacer.

Si copiaste con cp -R, repite el copy.

Cómo se desinstala​

rm ~/.claude/skills/grail   # o ~/.agents/skills/grail

El registry de proyectos (~/.grail/registry.json) es independiente del skill — bórralo manualmente si quieres una limpieza total.

Siguiente paso​