obsidian-cli

## Visión general de la skill obsidian-cli

### Para qué sirve realmente obsidian-cli
La skill `obsidian-cli` ayuda a un agente a operar una app de Obsidian en ejecución desde la línea de comandos. Es ideal para quienes quieren leer notas, crear o actualizar archivos, buscar en un vault, gestionar tareas o propiedades, o automatizar la depuración de plugins y temas sin tener que ir haciendo clic manualmente por la interfaz. Si tu necesidad real es “hacer cambios dentro de mi base de conocimiento” y no “resumir este repo”, esta skill encaja muy bien.

### Usuarios y flujos de trabajo para los que mejor encaja
Esta `obsidian-cli skill` resulta especialmente útil para usuarios avanzados de Obsidian, flujos de PKM, desarrolladores de plugins y equipos que usan Obsidian como base de conocimiento. Destaca sobre todo cuando ya tienes Obsidian abierto y quieres ejecutar acciones fiables sobre el vault actual o sobre un vault con nombre. Se centra menos en la estrategia abstracta de toma de notas y más en la ejecución precisa: leer, crear, buscar, inspeccionar, recargar, hacer capturas y depurar.

### Qué diferencia a obsidian-cli de un prompt genérico
Un prompt normal puede sugerir contenido para notas, pero `obsidian-cli` puede actuar directamente sobre el vault. Sus diferencias clave son:
- apunta a una instancia de Obsidian ya en ejecución
- admite tanto operaciones sobre contenido como flujos de UI y desarrollo
- usa formas de selección nativas de Obsidian como `file=<name>`, `path=<path>` y `vault=<name>`
- puede ayudar en el desarrollo de plugins o temas mediante recargas, ejecución de JavaScript, inspección del DOM, capturas de pantalla y captura de errores

### La principal limitación de adopción que conviene conocer primero
El bloqueo principal es simple: `obsidian-cli` requiere que Obsidian esté abierto. No es un analizador independiente de archivos para carpetas Markdown cualquiera. Funciona mejor cuando sabes qué vault quieres usar, si necesitas resolución de archivos al estilo wikilink o rutas exactas, y qué acción concreta debe ocurrir a continuación.

## Cómo usar la skill obsidian-cli

### Contexto de instalación y primeras comprobaciones
Para `obsidian-cli install` en un entorno con skills habilitadas, añade la skill del repo padre y luego invoca la skill cuando necesites operaciones en Obsidian. En la práctica, conviene comprobar antes estos puntos básicos:
- Obsidian está abierto
- el vault de destino ya está disponible en la app
- sabes si debes usar `vault=<name>`
- sabes si vas a apuntar por `file=<name>` o por `path=<path>`

Lee primero `skills/obsidian-cli/SKILL.md`. Es la fuente real de referencia aquí, porque la skill es ligera y está orientada a comandos. También ejecuta `obsidian help` en local para ver el conjunto actual de comandos, ya que la propia skill lo señala como la referencia más actualizada.

### Entradas que hacen que obsidian-cli funcione bien
Un buen `obsidian-cli usage` empieza con información de destino completa. Las solicitudes sólidas suelen incluir:
- nombre del vault
- nombre de la nota o ruta exacta
- acción deseada
- expectativas sobre sobrescritura
- formato del contenido, especialmente si hay texto multilínea

Mejor prompt:
“Use `obsidian-cli` to create a note in vault `Research` at `Projects/Agent Tests.md` with this markdown content, overwriting if it exists, then read it back to confirm.”

Prompt más débil:
“Make a note in Obsidian about testing.”

Por qué importa: la skill admite varios modos de selección, y omitir detalles de vault o ruta introduce conjeturas evitables.

### Patrones prácticos de comandos que conviene imitar
La sintaxis upstream es compacta y merece la pena seguirla tal cual:
- los parámetros usan `=`
- pon comillas en los valores con espacios
- los flags van como switches sin valor
- el contenido multilínea debe usar `\n`

Ejemplos:
- `obsidian create name="My Note" content="Hello world"`
- `obsidian create name="My Note" silent overwrite`
- `obsidian vault="My Vault" search query="test"`

Para seleccionar archivos, prioriza:
- `file=<name>` cuando el usuario piensa en títulos de nota
- `path=<path>` cuando importa la ubicación exacta
- `vault=<name>` primero cuando hay varios vaults abiertos o cuando el comportamiento basado en el foco reciente puede ser arriesgado

### Flujo de trabajo recomendado y qué leer primero
Una `obsidian-cli guide` práctica sería así:
1. Confirma que Obsidian está en ejecución.
2. Lee `SKILL.md`.
3. Ejecuta `obsidian help`.
4. Prueba primero un comando seguro de lectura o búsqueda.
5. Haz una única escritura con destino explícito.
6. Verifica el resultado leyendo de nuevo el archivo o buscando el texto insertado.

Si tu objetivo es trabajar con plugins o temas, empieza primero por comandos no destructivos: inspección, captura de pantalla, captura de errores, y solo después recarga o ejecución de JavaScript. Así obtienes feedback más rápido y reduces la confusión entre problemas de estado de la app y problemas de código.

## Preguntas frecuentes sobre la skill obsidian-cli

### ¿obsidian-cli sirve para la gestión normal de notas?
Sí. Si quieres leer notas, crear archivos, buscar en un vault, actualizar contenido o automatizar tareas repetitivas de una base de conocimiento, `obsidian-cli` encaja muy bien. Resulta especialmente útil cuando tus notas ya viven en Obsidian y quieres que las acciones se ejecuten dentro de la app en vivo, no solo editar Markdown de forma conceptual.

### ¿Cuándo no debería usar la skill obsidian-cli?
Evita `obsidian-cli` si:
- Obsidian no está abierto
- tus archivos son solo Markdown plano fuera de un flujo de trabajo de Obsidian
- necesitas automatización profunda de repositorios sin relación con un vault
- tu tarea es puramente editorial y no requiere actuar sobre la app

En esos casos, herramientas directas de sistema de archivos o un prompt de redacción normal pueden ser más simples.

### ¿obsidian-cli es apto para principiantes?
Moderadamente. La sintaxis es directa, pero los principiantes suelen pasar por alto el direccionamiento del vault y el comportamiento de resolución de archivos. La forma más fácil de empezar es con read/search/create sobre una nota de prueba. La depuración de plugins y temas es más avanzada, pero se aplica el mismo principio: usa destinos explícitos y verifica cada paso.

### ¿Cómo se compara obsidian-cli con simplemente pedirle algo a una IA?
Un prompt genérico de IA puede redactar contenido, pero la `obsidian-cli skill` aporta valor operativo. Puede ejecutar acciones sobre el vault, usar selección consciente de Obsidian y ayudar en tareas de depuración que la simple generación de texto no puede cubrir. La contrapartida es que debes aportar mejor contexto y tener la app en ejecución.

## Cómo mejorar la skill obsidian-cli

### Da mejores destinos, no prompts más largos
La forma más rápida de mejorar los resultados con `obsidian-cli` es ser específico sobre la ubicación y la intención. Incluye:
- nombre exacto del vault
- `file=` frente a `path=`
- si se permite sobrescribir
- salida esperada o paso de verificación

Mejora de ejemplo:
En vez de “update my meeting note,” di “Use `obsidian-cli` in vault `Work` to append the action items below to `Meetings/2025-02-Planning.md`, then read the final section back.”

### Evita los fallos más habituales
La mayoría de los malos resultados vienen de unos pocos problemas previsibles:
- Obsidian no está abierto
- se selecciona implícitamente el vault incorrecto
- `file=<name>` se resuelve de una forma distinta a la esperada
- el contenido multilínea se pasa sin `\n`
- se pide una escritura, pero no se solicita verificación

Si el primer intento falla, reduce el alcance: ejecuta una búsqueda o lectura, confirma el destino y luego vuelve a intentar la modificación.

### Usa un flujo de iteración y verificación
Para `obsidian-cli for Knowledge Bases`, el mejor flujo es trabajar en pasos pequeños y verificables:
1. buscar o leer
2. escribir un único cambio
3. leer de nuevo el resultado
4. solo entonces aplicar más cambios en lote

Esto importa más que un prompt ingenioso. Las bases de conocimiento son sensibles a convenciones de nombres, estructura de carpetas y metadatos, así que verificar evita desvíos silenciosos.

### Mejora la calidad de salida en trabajo de plugins y temas
Cuando uses `obsidian-cli` para desarrollo, pide evidencia observable, no solo acción. Las buenas solicitudes mencionan:
- qué plugin/tema hay que recargar
- qué página o estado se debe inspeccionar
- si hay que capturar errores, hacer una captura o inspeccionar el DOM
- cómo se ve el éxito

Ejemplo:
“Use `obsidian-cli` to reload my plugin, capture any console errors, inspect the target DOM element for the settings panel, and take a screenshot after reload.”  
Eso produce una salida de depuración mejor que “check why my plugin looks wrong.”