EastDong314/agent-skills

Notas de Obsidian

Contexto de Operación

Usa el vault local en ${OBSIDIAN_VAULT:-$HOME/workspace/notes}. Trátalo como una base de conocimiento propiedad del usuario y un codebase Markdown: preserva ediciones no relacionadas, evita reescrituras masivas a menos que se solicite, y mantén los nombres de archivo y enlaces de las notas amigables con Obsidian.

Normalmente este vault es la raíz del espacio de trabajo del agente, por lo que las tareas de notas habituales pueden usar las herramientas de archivo integradas (Codex: read/apply_patch; DSH y pi: read/edit/write). Para cualquier cosa fuera del vault, pregunta antes de escribir.

Esta habilidad es un paquete compartido por Codex, pi y DSH. Elige el directorio base que coincida con el agente actual, luego usa $HELPER en cada comando a continuación:

# DSH (copia de origen canónica)
export SKILL_DIR="$HOME/.dsh/skills/obsidian-notes"
# Codex
# export SKILL_DIR="$HOME/.codex/skills/obsidian-notes"
# pi
# export SKILL_DIR="$HOME/.pi/agent/skills/obsidian-notes"

export HELPER="$SKILL_DIR/scripts/obsidian_notes.py"
python3 "$HELPER" --help

Si SKILL_DIR nunca se exportó en el shell actual, expórtalo de nuevo por comando o resuelve scripts/obsidian_notes.py contra el directorio base de la habilidad que el harness reporta para esta habilidad. Usa python3 (el helper solo usa la biblioteca estándar; recurre a python solo si python3 no está disponible).

Prefiere este helper empaquetado para operaciones CRUD, index, log, lint, Bases y Canvas deterministas. Por defecto usa el vault y rechaza rutas fuera de él.

Usa la aplicación local de Obsidian o el esquema de URI obsidian:// para abrir notas cuando sea útil. En Linux Flatpak, el ID de la aplicación es md.obsidian.Obsidian; normalmente no hay un binario obsidian en PATH.

Esta habilidad es un superconjunto local y específico del vault de los patrones en kepano/obsidian-skills: Markdown con sabor Obsidian, Bases, JSON Canvas, uso de CLI y extracción web limpia. Mantén esos dominios en un solo flujo de trabajo para que las operaciones del vault permanezcan dentro del ámbito de ${OBSIDIAN_VAULT:-$HOME/workspace/notes}.

Modelo de Base de Conocimiento

Usa un modelo de tres capas para trabajos de conocimiento más grandes:

• Fuentes brutas: artículos, PDFs, recortes, notas de reuniones, capturas de pantalla o transcripciones proporcionados por el usuario. Trátalos como entradas de fuente de verdad; no los reescribas ni elimines a menos que se solicite explícitamente.
• Notas wiki: páginas Markdown estructuradas que el agente puede crear y mantener resumiendo, sintetizando, enlazando y actualizando.
• Esquema: esta habilidad más las notas de convención locales del vault bajo 技术/00-System/ y la carpeta de guía de Obsidian. Busca notas sobre el uso del vault, la taxonomía y las convenciones de Obsidian antes de hacer cambios no triviales.

Notas de esquema local del vault que vale la pena leer primero: AGENTS.md (raíz del vault, reglas de todo el vault), 技术/AGENTS.md (reglas locales de 技术/), 技术/00-System/目录结构说明.md, 技术/00-System/全局维护规则.md, 技术/00-System/分类与标签规范.md, 技术/00-System/知识库使用说明.md, 技术/00-System/文档模板说明.md y 技术/10-个人效率与环境/Obsidian/Obsidian知识管理使用规范.md.

Convenciones conocidas del vault que debes respetar:

• El contenido está escrito en chino; las notas son Markdown con YAML frontmatter que incluye al menos tags y related, y normalmente title/aliases/created/updated/type/status/source.
• Las carpetas raíz son AI/ (base de conocimiento principal, secciones numeradas), más 开发/, 日记/, 零星想法/, 项目/.
• La clasificación incierta pertenece a 98-待整理; el contenido obsoleto pertenece a 99-归档. Crea esas carpetas solo cuando algo realmente las necesite.
• Es preferible actualizar una nota existente de alto valor que sobrescribirla; si una fusión segura es imposible, crea un nuevo archivo con un sufijo "待合并".

Para trabajos no triviales, lee primero las notas de esquema relevantes. El objetivo es el conocimiento compuesto: actualiza páginas existentes, enlaces, entradas de índice y registros para que futuras sesiones no redescubran el mismo contexto desde cero.

Flujo de Trabajo

1. Aclara la operación a partir de la solicitud del usuario: crear, leer, actualizar, eliminar, buscar, ingerir, consultar, analizar (lint), organizar, abrir, crear una Base, crear un Canvas, recortar una fuente web o depurar el comportamiento de Obsidian.
2. Inspecciona las notas existentes antes de cambiar cualquier cosa:
   • Usa rg en Bash, o las herramientas de búsqueda de contenido/ruta del propio agente, para la búsqueda de contenido y rutas.
   • Usa los comandos search, read o list del helper para rutas dentro del ámbito del vault.
   • Lee las notas de esquema del vault cuando la estructura, la taxonomía o el mantenimiento a largo plazo sean importantes.
   • Revisa .obsidian/ solo cuando la configuración de la aplicación sea relevante.
3. Preserva la semántica de Obsidian:
   • Usa wikilinks como [[Nota Destino]] o [[Nota Destino|Alias]] para referencias internas.
   • Usa enlaces a encabezados [[Nota Destino#Encabezado]] y enlaces a bloques [[Nota Destino#^id-bloque]] cuando el usuario necesite referencias precisas.
   • Usa etiquetas en el frontmatter para una clasificación estable; usa #tags en línea solo cuando sean parte de la prosa.
   • Mantén el YAML frontmatter para metadatos, fechas, alias, estado, fuente, proyecto, área, modelo, anfitrión y próximas acciones.
   • Prefiere Properties de Obsidian y frontmatter compatible con Bases para campos estructurados. Usa campos en línea de Dataview como status:: activo solo cuando el usuario solicite explícitamente consultas de Dataview, campos en línea o un panel de Dataview.
   • Prefiere embeds relativos ![[archivo.png]] o ![[Nota#Encabezado]] al incrustar contenido del vault.
   • Usa callouts solo para contenido que se beneficie de énfasis visual: resúmenes, advertencias, ejemplos, decisiones, tareas pendientes y preguntas.
4. Realiza ediciones limitadas con la herramienta de parches/edición del agente (Codex: apply_patch; DSH y pi: edit), o usa write/el helper para crear o reemplazar notas completas. Lee un archivo antes de editarlo o reemplazarlo.
5. Para cambios duraderos, actualiza o regenera el índice y añade una entrada de registro.
6. Verifica después de las ediciones leyendo el archivo cambiado, comprobando enlaces/resultados de búsqueda, validando archivos .base o .canvas cuando estén presentes y, opcionalmente, abriendo la nota en Obsidian.

Reglas de Calidad de Notas

Para notas nuevas, crea notas que sean útiles dentro de Obsidian, no volcados Markdown simples:

• Comienza con YAML frontmatter a menos que la carpeta de destino tenga una convención contraria clara.
• Incluye aliases cuando el concepto tenga nombres alternativos.
• Incluye tags que coincidan con la taxonomía existente del vault cuando sea posible.
• Añade un primer párrafo conciso que indique de qué trata la nota.
• Añade secciones con encabezados que hagan posible el backlinking.
• Añade ## 相关链接 o ## Enlaces con wikilinks a notas existentes relevantes. Usa el encabezado localizado existente que la carpeta de destino ya utiliza: las carpetas AI/ numeradas usan ## 相关链接, las notas de proyecto pueden usar cualquiera.
• Pon los campos estructurados en YAML frontmatter por defecto para que Properties y Bases de Obsidian puedan editarlos, ordenarlos y filtrarlos. No dupliques el mismo campo como frontmatter y clave:: valor en el cuerpo a menos que el usuario solicite campos en línea de Dataview.
• Para notas de proyecto o tareas, incluye campos de estado procesable y próximos pasos.
• Para notas de conocimiento perenne, enlaza afirmaciones a notas fuente y conceptos relacionados.

Lee references/obsidian-patterns.md (bajo $SKILL_DIR) al crear nuevas plantillas de notas, reparar la estructura de notas o decidir cómo usar frontmatter, etiquetas, backlinks, Dataview, archivos de índice, registros y la ingestión de fuentes.

Funciones de Markdown de Obsidian

Usa estas funciones de sintaxis cuando hagan la nota más útil dentro de Obsidian:

• Wikilinks: [[Nota]], [[Nota|Alias]], [[Nota#Encabezado]], [[Nota#^id-bloque]], [[#mismo-encabezado-nota]].
• Embeds: ![[Nota]], ![[Nota#Encabezado]], ![[imagen.png|300]], ![[documento.pdf#page=3]], ![[Canvas.canvas]], ![[Vista.base#Nombre Vista]].
• Callouts: > [!note], > [!warning] Título, > [!todo]- Contraído, con líneas anidadas entre comillas para el contenido.
• Comentarios: %%texto oculto%% o comentarios de bloque para anotaciones solo del agente que no deben renderizarse.
• Resaltado/matemáticas/diagramas: ==resaltado==, $math$ en línea, bloque $$math$$, y mermaid con delimitación.
• Notas al pie: referencias [^1], definiciones y notas al pie en línea.

No sobreformatees las notas. Prefiere Markdown normal hasta que una extensión de Obsidian mejore la navegación, la recuperación o el renderizado.

Bases

Usa archivos .base cuando el usuario quiera vistas de tipo base de datos de notas, listas de tareas, listas de lectura, paneles de proyectos, índices filtrados o tablas/tarjetas/listas/mapas impulsados por propiedades.

Los archivos Base son YAML. Constrúyelos alrededor de:

• filters: expresiones globales y específicas de la vista como file.hasTag("proyecto"), file.inFolder("Notas Diarias"), status == "activo".
• formulas: campos calculados como días hasta vencimiento, etiquetas de estado, estimaciones de palabras o enlaces derivados.
• properties: nombres para mostrar y configuración para campos de notas, archivos y fórmulas.
• summaries: fórmulas agregadas como Promedio, Suma, Mín, Máx, Último, Verificado, Vacío, Lleno, Único.
• views: vistas de tabla, tarjetas, lista o mapa con order explícito.

Reglas:

• Pon entre comillas las expresiones de filtro y fórmula, especialmente cuando contengan :, #, corchetes, operadores de comparación o comillas anidadas.
• Envuelve las fórmulas que contengan comillas dobles entre comillas simples: 'if(done, "Yes", "No")'.
• La resta de fechas devuelve una duración. Accede a .days, .hours, etc. antes de las funciones numéricas.
• Protege las propiedades opcionales con if(property, expression, fallback).
• Valida después de editar: python3 "$HELPER" validate-base "Dashboards/Projects.base".

JSON Canvas

Usa archivos .canvas cuando el usuario solicite un mapa visual, panel de investigación, diagrama de flujo, mapa de dependencias, resumen de proyecto o canvas.

Los archivos Canvas son JSON con arrays de nivel superior nodes y edges:

• Los nodos requieren id, type, x, y, width y height.
• Los tipos de nodo son text, file, link y group.
• Las aristas requieren id, fromNode y toNode; los lados opcionales son top, right, bottom, left.
• Genera IDs hexadecimales únicos de 16 caracteres en minúsculas.
• Usa saltos de línea reales en los valores de cadena JSON, no \n literales a menos que el texto deba mostrar esos caracteres.
• Deja 50-100px entre nodos, alinea a una cuadrícula y mantén los nodos de grupo lo suficientemente grandes para contener a sus hijos.
• Valida después de editar: python3 "$HELPER" validate-canvas "Maps/Topic.canvas".

Recorte Web y Extracción de Fuentes

Cuando un usuario proporcione una URL para ingerir en el vault:

• Prefiere defuddle parse <url> --md cuando exista un comando local defuddle; extrae Markdown legible y elimina el desorden de navegación.
• defuddle no está instalado por defecto aquí; verifica primero, de lo contrario usa las herramientas de búsqueda/recuperación web del agente, luego guarda solo hechos duraderos y enlaces en el vault.
• No uses Defuddle para URLs que ya apunten a Markdown bruto.
• Preserva la URL de origen, autor/fecha si están disponibles, fecha de recuperación y estado de procesamiento en el frontmatter.
• Para fuentes largas, crea una nota de resumen de fuente y actualiza notas de conceptos/proyectos/entidades duraderos en lugar de volcar todo el artículo en la capa wiki.

CLI y Aplicación de Obsidian

Cuando Obsidian se esté ejecutando y haya un comando obsidian disponible, úsalo para acciones conscientes de la aplicación:

obsidian help
obsidian read file="Mi Nota"
obsidian search query="término" limit=10
obsidian property:set name="status" value="hecho" file="Mi Nota"
obsidian backlinks file="Mi Nota"
obsidian daily:append content="- [ ] Seguimiento"

Para depuración de complementos o temas, prefiere comandos conscientes de la aplicación después de cambios de código:

obsidian plugin:reload id=mi-plugin
obsidian dev:errors
obsidian dev:console level=error
obsidian dev:screenshot path=captura.png
obsidian dev:dom selector=".workspace-leaf" text

Si la CLI no está instalada u Obsidian no se está ejecutando, recurre a operaciones de archivo del vault y al esquema de URI obsidian://. El comando open del helper ya maneja la aplicación Flatpak y el fallback de URI:

python3 "$HELPER" open "技术/00-System/index.md"

Ingestión, Consulta y Lint

Usa el comportamiento de ingestión cuando el usuario proporcione una fuente o solicite agregar conocimiento desde un artefacto externo:

• Lee la fuente e identifica hechos duraderos, decisiones, conceptos, entidades, preguntas abiertas y contradicciones.
• Busca en el vault páginas existentes antes de crear nuevas.
• Crea una nota de resumen de fuente solo si será útil más adelante.
• Actualiza notas de conceptos/proyectos/entidades relevantes existentes, no solo la nueva página fuente.
• Añade backlinks y entradas related para que el nuevo conocimiento sea accesible desde notas existentes.
• Añade una entrada de registro describiendo qué se ingirió y qué páginas cambiaron.

Usa el comportamiento de consulta al responder desde el vault:

• Lee notas de índice/esquema primero cuando estén disponibles.
• Busca y lee notas relevantes antes de responder.
• Cita notas locales por wikilink o ruta en la respuesta.
• Si la respuesta crea una síntesis duradera, ofrece escribirla de vuelta como una nota o actualizar una nota existente.

Usa el comportamiento de lint para mantenimiento:

• Verifica falta de frontmatter, falta de secciones relacionadas, notas huérfanas, títulos duplicados, afirmaciones obsoletas, enlaces incorrectos y conceptos importantes que carecen de páginas.
• Prefiere informar un plan de reparación enfocado antes de hacer una limpieza amplia.
• Para la limpieza solicitada, repara enlaces y metadatos en pequeños lotes y registra el pase.

Comandos del Helper

El helper por defecto usa ${OBSIDIAN_VAULT:-$HOME/workspace/notes} (--vault para sobrescribir) y rechaza rutas fuera del vault. Ejecuta python3 "$HELPER" --help para la lista completa de comandos.

# Buscar títulos y contenido
python3 "$HELPER" search "consulta"

# Leer una nota por ruta relativa
python3 "$HELPER" read "AI/ejemplo.md"

# Crear una nota, incluyendo carpetas padre
python3 "$HELPER" create "AI/ejemplo.md" --title "Ejemplo" --tags project,active --body $'# Ejemplo\n\n...'

# Reemplazar una nota después de inspeccionarla
python3 "$HELPER" update "AI/ejemplo.md" --body "...markdown completo..."

# Eliminar solo cuando el usuario lo solicite explícitamente
python3 "$HELPER" delete "AI/nota-antigua.md" --yes

# Abrir una nota en Obsidian
python3 "$HELPER" open "AI/ejemplo.md"

# Crear y validar una Base
python3 "$HELPER" create-base "技术/00-System/proyectos-activos.base" --name "Proyectos Activos"
python3 "$HELPER" validate-base "技术/00-System/proyectos-activos.base"

# Crear y validar un Canvas
python3 "$HELPER" create-canvas "AI/Maps/resumen-proyecto.canvas"
python3 "$HELPER" validate-canvas "AI/Maps/resumen-proyecto.canvas"

# Regenerar un índice estilo wiki en 技术/00-System/index.md
python3 "$HELPER" index