Agent Skills
› NeverSight/learn-skills.dev
› cortexfs
cortexfs
GitHubCortexFS持久记忆技能，通过CLI实现项目知识的保存、读取和搜索。强制Agent先检索记忆再回答，并自动保存架构决策等重要信息，支持OpenCode和Cursor集成。
Trigger Scenarios
用户询问项目相关细节或历史决策
发现新的架构设计、代码规范或关键配置
会话中产生需跨周期保留的重要上下文
Install
npx skills add NeverSight/learn-skills.dev --skill cortexfs -g -y
SKILL.md
Frontmatter
{
"name": "cortexfs",
"description": "CortexFS Memory Skill - Persistent cognitive memory layer backed by CortexFS CLI. Allows saving, reading, searching knowledge and session states, scoped by project context. Includes automatic CLI installation and commands for OpenCode and Cursor. Todos los comandos son BASH\/CLI que deben ejecutarse en la TERMINAL\/SHELL."
}
CortexFS Memory Skill
Version: 0.6.0
Execution: Shell/Bash
Auth: None
🚀 AUTO-INSTALACIÓN (Ejecutar al inicio)
Cuando el skill se carga por primera vez, EL AGENTE DEBE ejecutar automáticamente estos comandos:
1. Instalar CortexFS CLI (si no existe)
if ! command -v cortex &> /dev/null; then
npm install -g cortexfs-cli
cortex config "$HOME/.cortexfs/brain"
fi
2. Copiar comandos a los agentes instalados
Para OpenCode:
mkdir -p ~/.config/opencode/commands
cp -r ~/.agents/skills/cortexfs/opencode-commands/* ~/.config/opencode/commands/
Para Cursor:
mkdir -p ~/.cursor/commands
cp -r ~/.agents/skills/cortexfs/opencode-commands/* ~/.cursor/commands/
Verificación:
which cortex || echo "NO_INSTALLED"
Si no está instalado, ejecutar:
npm install -g cortexfs-cli
Prerequisitos
- CortexFS CLI instalado
- Check:
which cortex || cortex --version - Install:
npm install -g cortexfs-cli
- Check:
🧠 COMPORTAMIENTO AUTOMÁTICO DEL AGENTE
Este skill actúa como la MEMORIA PERSISTENTE del proyecto. El agente DEBE seguir estas reglas de comportamiento:
🔍 REGLA 1: BUSCAR PRIMERO (Search-First)
Cuándo: SIEMPRE que el usuario pregunte algo sobre el proyecto, ANTES de responder o buscar en el código.
Acción:
- Ejecutar:
cortex search "<términos relevantes de la pregunta>" - Si hay resultados, usar
cortex readpara obtener el contenido completo - Usar ese conocimiento para responder o complementar la respuesta
Ejemplos:
| Pregunta del usuario | Ejecutar primero |
|---|---|
| "¿Cómo funciona la autenticación?" | cortex search 'autenticación auth login' |
| "¿Cuáles son las convenciones de código?" | cortex search 'convenciones código estilo' |
| "¿Qué decisiones de arquitectura tomamos?" | cortex search 'arquitectura decisiones' |
Por qué: CortexFS contiene conocimiento curado y decisiones previas. Buscar aquí PRIMERO evita repetir trabajo o contradecir decisiones.
💾 REGLA 2: GUARDAR CONOCIMIENTO IMPORTANTE (Auto-Save)
Cuándo: Guardar AUTOMÁTICAMENTE cuando se descubra o defina:
- Decisiones de arquitectura o diseño
- Convenciones de código acordadas
- Patrones o soluciones reutilizables
- Configuraciones importantes del proyecto
- APIs o endpoints documentados
- Bugs importantes y sus soluciones
- Dependencias clave y su propósito
- Flujos de negocio o lógica compleja
- Información que el usuario pide recordar
- Contexto importante que se perdería entre sesiones
Acción:
- Identificar la categoría apropiada
- Crear un ID semántico descriptivo
- Estructurar el contenido en JSON
- Ejecutar:
cortex save "<category>" "<id>" "<contenido JSON>"
📂 Categorías Recomendadas
| Categoría | Usar para |
|---|---|
arquitectura |
Decisiones de diseño, patrones, estructura |
convenciones |
Reglas de código, estilo, naming |
config |
Configuraciones, variables de entorno, settings |
api |
Endpoints, contratos, schemas |
bugs |
Problemas encontrados y soluciones |
flujos |
Lógica de negocio, workflows, procesos |
dependencias |
Librerías importantes y su uso |
memoria |
Información general que recordar |
🔄 REGLA 3: INICIO DE SESIÓN (Session Start)
Cuándo: Al inicio de una nueva conversación o sesión.
Acción:
- Ejecutar:
cortex load-state - Revisar el estado anterior para contexto
- Ejecutar:
cortex list - Conocer qué conocimiento está disponible
Por qué: Retomar contexto sin que el usuario tenga que repetir información.
🏁 REGLA 4: FIN DE SESIÓN (Session End)
Cuándo:
- El usuario indica que termina la sesión
- Se completó una tarea importante
- Hubo cambios significativos en el proyecto
Acción: Ejecutar cortex save-state con JSON estructurado:
{
"task": "qué se estaba haciendo",
"status": "in_progress|blocked|review",
"progress": {
"completed": [],
"pending": [],
"blocked": []
},
"context": {
"files_modified": [],
"branch": ""
},
"next_steps": []
}
📋 COMANDOS DISPONIBLES
cortex config
Configura el directorio raíz del brain.
cortex config "<path>"
Ejemplo:
cortex config '/ruta/al/brain'
cortex save
Guarda conocimiento estructurado. SIEMPRE estructurar el contenido en JSON o Markdown.
cortex save "<category>" "<id>" "<content>"
Parámetros:
category: Categoría del conocimiento (ej: arquitectura, convenciones)id: Identificador semánticocontent: Contenido - DEBE ser JSON estructurado o Markdown organizado
Ejemplo JSON:
cortex save 'agent' 'mi-agente' '{"name":"mi-agente","role":"asistente","capabilities":["buscar","analizar"]}'
Ejemplo Markdown:
cortex save 'project' 'readme' '# Proyecto\n\n## Descripción\nTexto aquí...'
cortex read
Lee conocimiento persistido.
cortex read "<category>" "<id>"
Ejemplo:
cortex read 'agent' 'mi-agente'
cortex update
Actualiza conocimiento existente.
cortex update "<category>" "<id>" "<content>"
Ejemplo:
cortex update 'agent' 'mi-agente' 'nuevo contenido'
cortex delete
Elimina conocimiento.
cortex delete "<category>" "<id>"
Ejemplo:
cortex delete 'agent' 'mi-agente'
cortex list
Lista conocimiento, opcionalmente filtrado por categoría.
cortex list [category]
Ejemplos:
cortex list # Lista todas las categorías
cortex list 'agent' # Lista entradas en categoría 'agent'
cortex search
Busca conocimiento por query.
cortex search "<query>"
Ejemplo:
cortex search 'mi búsqueda'
cortex save-state
Guarda el estado de la sesión. SIEMPRE usar formato estructurado para facilitar handoff.
cortex save-state "<summary>"
Formato recomendado JSON:
cortex save-state '{"task":"Implementar auth","status":"in_progress","progress":{"completed":["login"],"pending":["logout"]},"next_steps":["agregar tests"]}'
Alternativa compacta:
cortex save-state 'TASK: Auth OAuth2 | STATUS: in_progress | DONE: login | PENDING: logout | NEXT: tests'
cortex load-state
Carga el estado más reciente de la sesión.
cortex load-state
⚡ FLUJO DE TRABAJO OBLIGATORIO
┌─────────────────────────────────────────────────────────┐
│ INICIO DE SESIÓN │
│ 1. cortex load-state → Recuperar contexto anterior │
│ 2. cortex list → Ver conocimiento disponible │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ CUANDO EL USUARIO PREGUNTE ALGO │
│ 1. cortex search "..." → BUSCAR PRIMERO en memoria │
│ 2. cortex read "..." "..." → Leer detalles si existe │
│ 3. Luego buscar en código si es necesario │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ CUANDO DESCUBRAS/DEFINAS ALGO IMPORTANTE │
│ → cortex save "categoria" "id" "{...JSON...}" │
│ │
│ Guardar: decisiones, convenciones, configs, APIs, │
│ bugs+soluciones, patrones, flujos de negocio │
└─────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────┐
│ FIN DE SESIÓN / TAREA COMPLETADA │
│ → cortex save-state "{...estado estructurado...}" │
└─────────────────────────────────────────────────────────┘
🔍 Ejemplo Completo: Usuario pregunta algo
Usuario: "¿Cómo manejamos los errores en la API?"
# PASO 1: Buscar primero en CortexFS
cortex search "errores API manejo error handling"
# PASO 2: Si encuentra resultados, leer el contenido
cortex read "convenciones" "error-handling"
# PASO 3: Responder usando ese conocimiento + código si necesario
💾 Ejemplo Completo: Guardar conocimiento importante
Después de definir cómo manejar errores:
cortex save "convenciones" "error-handling" '{
"topic": "Manejo de errores en API",
"rules": [
"Usar AppError para errores controlados",
"Logging con nivel según severidad",
"Respuestas estandarizadas con code y message"
],
"example": "throw new AppError(400, \"VALIDATION_ERROR\", \"Campo requerido\")",
"decided_on": "2024-01-15",
"reason": "Consistencia en respuestas de error"
}'
⚠️ Recordatorios Críticos
- BUSCAR ANTES DE RESPONDER - CortexFS tiene conocimiento curado
- GUARDAR PROACTIVAMENTE - Si es importante, persistirlo
- ESTRUCTURAR EN JSON - Facilita búsqueda y lectura futura
- Los comandos
cortexson ejecutables BASH del sistema - Requieren permisos de escritura fuera del workspace (usar "all")
Version History
- e0220ca Current 2026-07-05 22:07
