Obsidian Skills: enseñar a un agente de IA a escribir Obsidian como lo hace un humano

Todo lo que hay que saber sobre kepano/obsidian-skills: el paquete de habilidades (agent skills) oficial del equipo de Obsidian que permite a agentes como Claude Code, Codex u OpenCode leer y editar Markdown de Obsidian, Bases, JSON Canvas y controlar el propio CLI de Obsidian.

Qué es obsidian-skills

obsidian-skills es un paquete de «habilidades de agente» (agent skills) para Obsidian, publicado por el propio autor de varios proyectos de la plataforma. No es un plugin, un modelo ni una herramienta de ejecución: el producto son archivos de instrucciones en Markdown, uno por habilidad, que un agente compatible con la especificación Agent Skills (agentskills.io/specification) carga para saber exactamente cómo escribir archivos válidos de Obsidian.

Su propósito es cerrar una brecha concreta: un agente generalista no conoce las extensiones propias de Obsidian —enlaces internos tipo [[wikilink]], incrustaciones ![[...]], callouts > [!note], propiedades (frontmatter), Bases (.base) ni el formato JSON Canvas (.canvas)— y por eso genera notas que Obsidian no renderiza bien o que rompen los enlaces y las vistas. obsidian-skills aporta la sintaxis correcta y los flujos de trabajo para que el agente produzca y edite esos archivos con seguridad.

A 11 de septiembre de 2026 el paquete documenta seis habilidades: obsidian-markdown, obsidian-bases, json-canvas, obsidian-cli, defuddle y knap. El README las presenta como compatibles con «cualquier agente compatible con skills», citando explícitamente a Claude Code, Codex y OpenCode.

El origen: un autor de la propia Obsidian

El repositorio fue creado el 2 de enero de 2026 por Steph Ango (kepano), cuya cuenta de GitHub identifica a Obsidian como empresa y enlaza a su blog stephango.com y a su cuenta de X @kepano. Ango es también el autor de varios proyectos prominentes vinculados a la plataforma: el tema obsidian-minimal (5.373 estrellas), el extractor defuddle (9.353 estrellas) y el esquema de color flexoki (3.655 estrellas), además de su bóveda personal kepano-obsidian (4.504 estrellas). Esto convierte a obsidian-skills en el paquete «de primera parte»: no es una aproximación externa a Obsidian, sino la guía que el propio equipo detrás de la aplicación publica para que los agentes usen sus formatos y su CLI.

Los primeros commits son instructivos. El 2 de enero de 2026 se añadieron las habilidades de Obsidian Markdown y Bases (el mismo día que se creó el repo) y el 6 de enero la de JSON Canvas. El 10 de febrero de 2026 llegaron defuddle y obsidian-cli, y el 10 de septiembre de 2026 se incorporó knap. El crecimiento fue de abajo hacia arriba: primero los formatos de archivo que ya existían, después la interacción con la aplicación y, por último, la generación de plantillas desde datos estructurados.

Filosofía y principios

Formatos abiertos, no API cerrada. El README subraya que las habilidades enseñan a usar «formatos abiertos, incluidos Markdown, Bases y JSON Canvas». La apuesta es que un agente puede trabajar sobre archivos planos y legibles sin depender de una API propietaria.

Sintaxis exacta, no aproximada. Cada habilidad documenta la sintaxis completa (wikilinks, bloques, callouts, esquemas de Bases, especificación JSON Canvas 1.0) y, sobre todo, el paso de verificación: validar el YAML de un .base, comprobar que los fromNode/toNode de un canvas resuelven a nodos existentes, o confirmar que una nota se renderiza en la vista de lectura.

Reutilizabilidad multi-agente. Al seguir la especificación Agent Skills, una sola habilidad sirve para Claude Code, Codex y OpenCode sin reescribirla. El README y el PR #27 («Align skills with Agent Skills spec and Codex») muestran que la compatibilidad se trata como un requisito, no como un extra.

Componibilidad con herramientas adyacentes. defuddle (extraer Markdown limpio de una web) y knap (renderizar plantillas desde JSON/CSV) se integran en el mismo flujo: capturar, transformar y guardar en la bóveda, reduciendo el consumo de tokens.

Cómo funciona

El paquete es una carpeta skills/ con un subdirectorio por habilidad, cada uno con un SKILL.md (frontmatter con name y description) y, en algunos casos, referencias adicionales:

Habilidad	Archivo objetivo	Qué enseña al agente
`obsidian-markdown`	`.md`	Wikilinks, incrustaciones, callouts, propiedades, comentarios `%%...%%`, resaltado, matemáticas LaTeX, Mermaid y pies de página.
`obsidian-bases`	`.base`	Bases como archivos YAML con `filters` (and/or/not), `formulas`, `summaries` y vistas `table`/`cards`/`list`/`map`.
`json-canvas`	`.canvas`	Especificación JSON Canvas 1.0: `nodes` y `edges`, IDs hexadecimales de 16 caracteres únicos, `fromNode`/`toNode`, anclajes `fromSide`/`toSide`.
`obsidian-cli`	Bóveda (aplicación)	Interactuar con una instancia de Obsidian en marcha mediante el CLI `obsidian`: leer, crear, buscar, gestionar notas, tareas y propiedades; y desarrollar plugins/temas (`plugin:reload`, `dev:errors`, `dev:screenshot`, `dev:dom`, `dev:console`, `eval`).
`defuddle`	Web → Markdown	Extraer contenido limpio con el CLI `defuddle parse <url> --md` para ahorrar tokens frente a `WebFetch`.
`knap`	Datos → Markdown	Renderizar plantillas con variables `{{ var }}`, filtros y lógica `{% ... %}` desde JSON/CSV, y generar lotes de archivos.

Las habilidades de formato se activan por descripción: el frontmatter indica «úsalo cuando el usuario mencione wikilinks, callouts, frontmatter, etiquetas o incrustaciones», de modo que el agente decide en qué momento cargarlas. obsidian-cli añade un ciclo de desarrollo de plugins documentado paso a paso (recargar → revisar errores → verificar con captura o DOM → revisar consola).

Estado oficial / semioficial

Paquete del propio equipo de Obsidian. El autor identifica a Obsidian como su empresa y ya es el creador del tema Minimal, de Defuddle y de flexoki. Es, en la práctica, la referencia «oficial» de cómo un agente debe escribir los formatos de Obsidian.

Formato estándar de facto (Agent Skills). Todas las habilidades siguen la especificación agentskills.io/specification, el mismo estándar que usan Claude Code, Codex y OpenCode. Eso significa que el paquete no depende de un agente concreto y que es portable a cualquier implementación compatible.

Instalable desde el marketplace oficial de plugins de Claude Code. El README ofrece /plugin marketplace add kepano/obsidian-skills seguido de /plugin install obsidian@obsidian-skills, y el repo incluye .claude-plugin/marketplace.json y plugin.json (nombre obsidian, versión 1.0.1). La presencia en el mecanismo de marketplaces de Claude no implica una certificación de calidad por parte de Anthropic, pero sí que el paquete se distribuye por el canal oficial de ese agente.

Dependencia de una función oficial de Obsidian. La habilidad obsidian-cli se apoya en el Obsidian CLI, una función nativa de la aplicación documentada en help.obsidian.md/cli y presentada por la propia empresa (hilo de Hacker News 46961430, «Obsidian Introduces Obsidian CLI»). En otras palabras, parte del valor del paquete deriva de una capacidad que Obsidian expone de forma oficial.

En la práctica, esto sitúa a obsidian-skills como el punto de partida natural para cualquier persona que quiera que un agente de código opere sobre una bóveda de Obsidian, antes de valorar alternativas comunitarias.

El ecosistema

Repositorios compañeros del autor

kepano/defuddle — extractor HTML→Markdown («Get the main content of any page as Markdown»); 9.353 estrellas y 403 bifurcaciones, TypeScript, creado el 27 de febrero de 2025, sitio defuddle.md. Es la herramienta que usa la habilidad defuddle. En npm, el paquete defuddle (versión 0.19.3) registró 445.470 descargas entre el 4 y el 10 de septiembre de 2026 y 2.398.182 descargas en el mes anterior. kepano/defuddle-cli — versión anterior del CLI, hoy marcada como «Moved to the main defuddle repo»; 508 estrellas. obsidianmd/knap — «A simple template language that turns data into Markdown»; 251 estrellas y 6 bifurcaciones, TypeScript, creado el 21 de agosto de 2026, sitio knap.md, perteneciente a la organización obsidianmd. En npm, el paquete knap (versión 0.4.2) registró 705 descargas en la semana del 4 al 10 de septiembre de 2026.

Otros proyectos del autor: kepano/obsidian-minimal (tema sin distracciones, 5.373 estrellas), kepano/kepano-obsidian (plantilla de bóveda personal, 4.504 estrellas), kepano/flexoki (esquema de color «inky», 3.655 estrellas), kepano/clipper-templates (plantillas para el Obsidian Web Clipper, 1.442 estrellas), kepano/40-questions (1.666 estrellas), y kepano/datacore (sucesor work-in-progress de Dataview, 0 estrellas).

Habilidad de instalación: `npx skills`

El README instala también mediante npx skills add .... El paquete npm skills (versión 1.5.25) corresponde al repositorio vercel-labs/skills, descrito como «The open agent skills ecosystem». No es una herramienta de Obsidian, sino un instalador genérico del ecosistema de Agent Skills que el README reutiliza para añadir este paquete.

Puertos, packs y proyectos relacionados de la comunidad

La comunidad ha generado su propio conjunto de packs y utilidades para agentes que operan sobre Obsidian, varios de los cuales aparecieron como Show HN en Hacker News: vladignatyev/brain-map-skill — «Skill for your agent to visualize your gbrain and Obsidian»; hilo HN 48514124 con 23 puntos y 17 comentarios (13 de junio de 2026). anliberant/obsidian-ai-setup — «Obsidian AI Setup – A production-ready onboarding skill for AI agents»; hilo HN 48771700 (3 de julio de 2026). ballred/obsidian-claude-pkm — «Obsidian and Claude Code PKM Starter Kit»; hilo HN 46379291 (24 de diciembre de 2025). axtonliu/axton-obsidian-visual-skills — «Obsidian Visual Skills – Generate Canvas, Excalidraw, Mermaid from Text»; hilo HN 46970701 (11 de febrero de 2026). voicetreelab/voicetree — «Obsidian meets Claude Code. A Markdown graph for agents and context»; hilo HN 46878200 (3 de febrero de 2026). acertainKnight/project-thoth — «Thoth – Obsidian AI Research Assistant»; hilo HN 46968889 (11 de febrero de 2026).

Estas cifras son las que devolvió la API de Hacker News durante esta investigación; no constituyen una auditoría de calidad ni de compatibilidad de cada derivado.

Guía rápida de uso

Instalación y primer arranque

# 1) Marketplace (Claude Code)
/plugin marketplace add kepano/obsidian-skills
/plugin install obsidian@obsidian-skills

# 2) npx skills (cualquier agente compatible con Agent Skills)
npx skills add git@github.com:kepano/obsidian-skills.git
# o, si se prefiere HTTPS:
npx skills add https://github.com/kepano/obsidian-skills

# 3) Manual
#    - Claude Code: copia el contenido del repo en la carpeta /.claude de la raíz de la bóveda.
#    - Codex: copia la carpeta skills/ en la ruta de skills de Codex (típicamente ~/.codex/skills).
#    - OpenCode: clona el repo completo en el directorio de skills de OpenCode:
git clone https://github.com/kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills

En el primer arranque, el agente detecta los SKILL.md disponibles (OpenCode autodetecta todos los SKILL.md bajo ~/.opencode/skills/ y no requiere cambios en opencode.json; las habilidades quedan activas tras reiniciar OpenCode). A partir de ahí, basta pedirle al agente una tarea sobre la bóveda («crea una nota», «busca en mi bóveda», «captura esta página») y este cargará la habilidad pertinente por su description.

Flujos de trabajo habituales

Crear una nota válida de Obsidian. El flujo obsidian-markdown le indica al agente: añadir frontmatter (title, tags, aliases), escribir el contenido, enlazar con [[wikilink]] para notas internas, incrustar con ![[...]], añadir callouts > [!tip] y, al final, verificar que se renderiza en la vista de lectura.
Consultar la bóveda por línea de comandos. Con obsidian-cli, para leer una nota: obsidian read file="My Note"; para buscar: obsidian search query="search term" limit=10; para añadir una tarea al diario: obsidian daily:append content="- [ ] New task".
Capturar una web y guardarla en la bóveda. La pipeline defuddle + knap:
```
defuddle parse https://example.com/article --md --json \
  | knap render template.md --data - -o note.md
```
Defuddle entrega el contenido limpio como JSON (title, content, …) y Knap lo vierte en una plantilla, generando note.md.
Generar un lote de notas desde datos. Con knap batch:
```
knap batch template.md --data articles.csv --output-dir notes \
  --filename '{{ title | safe_name }}.md'
```
Una fila de CSV (u objeto JSON) por archivo, con --dry-run para validar sin escribir.

Configuración esencial

skills/<nombre>/SKILL.md — el archivo de cada habilidad. El frontmatter con name y description es lo que el agente lee para decidir cuándo activarla.
Ruta de instalación por agente — /.claude (Claude Code, en la raíz de la bóveda), ~/.codex/skills (Codex) o ~/.opencode/skills/ (OpenCode). El README insiste en que, para OpenCode, hay que clonar el repo completo, no solo la carpeta interior skills/.
defuddle y knap (CLIs opcionales) — si no están instalados, npm install -g defuddle y npm install -g knap (Knap requiere Node.js 20 o posterior; también funciona con npx knap).
obsidian CLI — la habilidad obsidian-cli exige que Obsidian esté abierto para interactuar con la bóveda; obsidian help muestra los comandos disponibles.
.claude-plugin/marketplace.json y plugin.json — metadatos del plugin para el marketplace de Claude Code; normalmente no se tocan.

Trampas frecuentes y soluciones

El CLI no responde. La habilidad obsidian-cli documenta que «Requiere Obsidian abierto». Si obsidian ... no hace nada, abrir la aplicación primero.
OpenCode no ve las habilidades. Copiar solo la carpeta interior skills/ rompe la estructura esperada. El README exige clonar el repo completo de modo que la ruta sea ~/.opencode/skills/obsidian-skills/skills/<skill-name>/SKILL.md, y reiniciar OpenCode.
Bases falla al renderizarse. obsidian-bases enumera los fallos típicos: cadenas YAML sin comillas que contienen caracteres especiales, comillas desequilibradas en las expresiones de fórmula, o referenciar formula.X sin definir X en formulas.
Colisiones de ID en canvas. La habilidad json-canvas avisa de que cada nodo y arista necesita un ID hexadecimal de 16 caracteres único y que hay que comprobar que todo fromNode/toNode resuelve a un nodo existente antes de guardar.
defuddle sobre URLs .md. La description de defuddle indica explícitamente: no usar para URLs que terminan en .md; usar WebFetch directamente. El PR #41 («Skip defuddle for .md URLs») refuerza esta regla.
knap sin Node 20. Knap requiere Node.js 20 o posterior; con versiones anteriores conviene usar npx knap o actualizar el runtime.

Integraciones y migración

Al seguir agentskills.io/specification, el paquete se integra sin cambios en Claude Code, Codex y OpenCode, y en cualquier agente compatible; no hay «migración» entre agentes, solo cambia la ruta de instalación. obsidian-cli conecta el agente con la aplicación en marcha para operaciones en vivo, complementando la edición directa de archivos de las otras habilidades. Defuddle y Knap se encadenan para capturar contenido web y renderizarlo en notas. Para plantillado, Knap es una alternativa al plugin Templater; para consultas sobre notas, Bases ocupa el terreno de plugins de datos como Dataview (del que existe además kepano/datacore como sucesor en desarrollo).

Números del repo

Medición: 11 de septiembre de 2026, API de GitHub.

Métrica	Valor
Estrellas	48.174
Bifurcaciones	3.437
Suscriptores reales (watchers)	249
Commits	47
Incidencias abiertas indicadas por la API	71
Lenguaje principal	(sin clasificar; el repo es Markdown)
Licencia	MIT
Creación	2 de enero de 2026
Último push	10 de septiembre de 2026

Los principales contribuidores, por número de contribuciones: kepano (31), Ethereal49 (2) y un amplio conjunto de colaboradores con una contribución cada uno (popey, mourjo, chiahsien, petersolopov, SDGLBL, shreyas-makes, SublimePeace, thibaultmol, chenminhua, costa92, Vinluo, zillydev, entre otros). Dos caveats de la API: watchers_count en la respuesta general replica las estrellas, por lo que el número de suscriptores reales es el campo subscribers_count (249); y open_issues_count (71) puede incluir solicitudes de cambios abiertas, así que no debe leerse como un conteo exclusivo de incidencias.

Cómo contribuir

El repositorio no incluye un CONTRIBUTING.md ni un arnés de pruebas documentado, y es un proyecto pequeño (47 commits). El proceso efectivo, inferido del historial real de pull requests fusionados, es el flujo estándar de GitHub: bifurcar, abrir una rama, enviar un PR contra main. El historial muestra PRs aceptados de la comunidad, por ejemplo #27 (alinear skills con la especificación Agent Skills y Codex), #37, #41, #43, #44, #59 (ejemplo de incrustación en Bases), #64 (saltar .md en defuddle), #66, #68 (corregir el esquema de filtros de Bases) y #94 (actualizar la URL de defuddle al nuevo repo). En la práctica, las contribuciones son correcciones de sintaxis, documentación de esquemas y alineación de la compatibilidad multi-agente, revisadas y fusionadas por el autor.

Cómo lo recibió la comunidad

La evidencia recuperada muestra adopción y actividad, pero conviene matizar: no se localizó un hilo de lanzamiento de obsidian-skills con una discusión amplia y verificable en Hacker News. En su lugar, el contexto se apoya en dos hilos fuertes del ecosistema y en varios Show HN de packs comunitarios.

El hilo 46961430 «Obsidian Introduces Obsidian CLI» (44 puntos, 7 comentarios, 10 de febrero de 2026) recoge la recepción de la función sobre la que se apoya la habilidad obsidian-cli. El usuario joshstrange señaló una limitación concreta: «sigues teniendo que mantener la UI abierta para que el CLI funcione, lo cual es lamentable», aunque «aprecio mucho el control añadido». presbyterian observó que gran parte ya era posible «ya que está construido casi por completo sobre archivos de texto planos». Surac preguntó qué caso de uso estaba apuntando.

El hilo 44067409 «Show HN: Defuddle, an HTML-to-Markdown alternative to Readability» (418 puntos, 68 comentarios, 22 de mayo de 2025) muestra la recepción del compañero defuddle. creakingstairs contó haberlo encontrado «revisando el código fuente del obsidian web-clipper» y quedar «impresionado con sus resultados de conversión a markdown». billconan preguntó si usaba modelos de IA «por detrás». tmpfs afirmó haber estado «investigando esto recientemente y ciertamente no impresionado con la calidad de las implementaciones de Readability en varios lenguajes».

En el flanco de packs comunitarios, el Show HN 48514124 («brain-map-skill») alcanzó 23 puntos y 17 comentarios, y 49394827 («OzBrain, a shared brain for knowledge between agents and your team») obtuvo 93 puntos y 59 comentarios, señal de un interés sostenido en dar a los agentes acceso a bóvedas tipo Obsidian. No se recuperaron críticas verificables al propio obsidian-skills más allá de las limitaciones del CLI (requerir la UI abierta).

obsidian-skills frente a otras propuestas

Propuesta	Coincidencia verificable	Diferencia verificable
`kepano/defuddle`	Herramienta del mismo autor que obsidian-skills usa (habilidad `defuddle`) para capturar webs como Markdown.	Defuddle es un extractor HTML→Markdown autónomo (9.353 estrellas); obsidian-skills es el conjunto de instrucciones que lo invoca junto a otras habilidades.
`obsidianmd/knap`	Herramienta de la organización `obsidianmd` que obsidian-skills usa (habilidad `knap`) para renderizar plantillas desde datos.	Knap es un motor de plantillas TypeScript (251 estrellas); obsidian-skills enseña al agente a orquestar Knap, no reemplaza el motor.
Readability (`mozilla/readability`)	Baseline de extracción de contenido web a la que Defuddle (y, por extensión, la pipeline de obsidian-skills) se opone.	Readability es una librería de extracción clásica; la pipeline de obsidian-skills la sustituye por Defuddle + Knap para alimentar una bóveda.
Packs comunitarios	Packs de habilidades que hacen que un agente opere sobre Obsidian.	Son packs de terceros centrados en un nicho (PKM, onboarding, visuales, mapeo de conocimiento); obsidian-skills es el paquete del propio equipo de Obsidian y cubre los formatos oficiales (Markdown, Bases, Canvas) más el CLI.
Plugins internos (Templater, Dataview)	Cubren plantillado y consultas sobre notas dentro de la aplicación.	Son plugins de la UI de Obsidian; obsidian-skills orienta a un agente a usar `knap` y `obsidian-bases` para lograr el mismo resultado por línea de comandos / agente.

La comparación más útil no es por popularidad: obsidian-skills destaca cuando se necesita una referencia «de primera parte» sobre la sintaxis oficial de Obsidian para un agente multi-plataforma. Un pack comunitario especializado puede ser preferible cuando el objetivo concreto (PKM, visuales, mapeo) excede lo que las habilidades oficiales documentan.

Casos de uso

Personas con una bóveda de Obsidian que usan Claude Code, Codex u OpenCode pueden adoptar el paquete para que el agente cree, edite y enlace notas con wikilinks, incrustaciones, callouts y frontmatter correctos, sin romper la sintaxis ni las vistas.
Usuarios del Obsidian CLI (y desarrolladores de plugins/temas) pueden apoyarse en la habilidad obsidian-cli para que el agente lea, busque y modifique la bóveda en vivo, y para el ciclo de desarrollo de plugins.
Flujos de captura y publicación de contenido pueden encadenar defuddle parse <url> --md --json | knap render ... para convertir una web en una nota de la bóveda, y usar knap batch para generar lotes de notas desde CSV/JSON.
Quienes gestionan datos sobre notas (proyectos, tareas, lecturas) pueden pedir al agente que construya .base con filters, formulas y vistas table/cards/list/map, delegando en Obsidian Bases el papel de «base de datos» sobre el Markdown.
Equipos que estandarizan cómo un agente escribe Obsidian pueden distribuir este paquete (vía marketplace de Claude Code o npx skills) como la referencia común.

Recursos

Repositorio: https://github.com/kepano/obsidian-skills
Documentación/instalación: https://github.com/kepano/obsidian-skills#installation
Habilidades oficiales: https://github.com/kepano/obsidian-skills/tree/main/skills
Especificación Agent Skills: https://agentskills.io/specification
Obsidian CLI (función oficial): https://help.obsidian.md/cli
Defuddle: https://github.com/kepano/defuddle · https://defuddle.md
Knap: https://github.com/obsidianmd/knap · https://knap.md
Instalador npx skills (vercel-labs): https://github.com/vercel-labs/skills
Registros de paquetes (npm): https://www.npmjs.com/package/defuddle · https://www.npmjs.com/package/knap · https://www.npmjs.com/package/skills
Hilos de Hacker News relevantes: https://news.ycombinator.com/item?id=46961430 (Obsidian CLI) · https://news.ycombinator.com/item?id=44067409 (Defuddle) · https://news.ycombinator.com/item?id=48514124 (brain-map-skill) · https://news.ycombinator.com/item?id=46379291 (obsidian-claude-pkm) · https://news.ycombinator.com/item?id=48771700 (obsidian-ai-setup)
Comunidad / X del autor: https://x.com/kepano · blog https://stephango.com

Nota: este artículo combina el README y los archivos SKILL.md de obsidian-skills, los metadatos de la API de GitHub, el registro npm, la API de Hacker News y el perfil del autor, consultados el 11 de septiembre de 2026. Las cifras de estrellas, descargas y puntos cambian con el tiempo.