CEO của Obsidian tự tay xây bộ skill dạy AI agent dùng Obsidian

TL;DR

Steph Ango - CEO của Obsidian, người đứng sau triết lý "file over app" - vừa tự tay xây và public lên GitHub bộ obsidian-skills: 5 file hướng dẫn giúp AI agent làm việc đúng với các định dạng riêng của Obsidian. Bộ skill đạt hơn 41.000 stars và tiếp tục tăng nhanh. MIT license, miễn phí hoàn toàn, dùng được với Claude Code, Codex CLI, OpenCode và Gemini CLI.

Vấn đề: AI agent không hiểu "ngôn ngữ" Obsidian

Obsidian không phải Markdown thông thường. Bên cạnh cú pháp Markdown cơ bản, nó còn có wikilinks ([[Tên ghi chú]]) để liên kết các ghi chú với nhau, callouts (> [!note]) để tạo khung nhấn mạnh, và properties - khối YAML ở đầu mỗi file để lưu metadata như ngày tạo, tag, status.

Tính năng Bases ra mắt trong Obsidian 1.9 còn mang thêm file .base - một định dạng biến YAML properties thành bảng dữ liệu có thể lọc, sắp xếp và tính toán, gần giống database nhỏ nhưng toàn bộ dữ liệu vẫn nằm trong Markdown files thông thường. File .canvas là JSON có cấu trúc riêng cho sơ đồ tư duy.

Khi dùng AI agent như Claude Code để làm việc trong vault Obsidian, agent thường viết plain Markdown tiêu chuẩn - đúng về kỹ thuật nhưng bỏ qua toàn bộ tính năng Obsidian-specific. Wikilink bị viết thành hyperlink thường, properties sai format, Bases không tạo được, Canvas file rỗng. Agent cần được "dạy" cụ thể mới làm đúng.

obsidian-skills là gì

Trong chuẩn Agent Skills specification do Anthropic công bố, một "skill" là một folder chứa file SKILL.md - tập hợp hướng dẫn chuyên biệt. Khi được load vào agent, nó cho agent biết chính xác cách thực hiện một loại công việc theo đúng format yêu cầu. Không binary, không extension, không dependency - chỉ là Markdown thuần.

obsidian-skills là bộ 5 folder skill như vậy, được chính Steph Ango - người thiết kế Obsidian từ đầu - viết dựa trên syntax và convention thực tế của từng tính năng. Đây là nguồn chính thức, không phải community hack hay reverse-engineering từ docs. Hơn 41.000 stars trong thời gian ngắn là tín hiệu rõ về mức độ quan tâm của cộng đồng Obsidian.

5 Skills trong bộ

Bộ gồm 5 skill, mỗi skill giải quyết một định dạng cụ thể:

• obsidian-markdown - Skill nền tảng. Dạy agent cách viết đúng Obsidian Flavored Markdown: wikilinks [[Tên ghi chú]], embeds ![[file]], callouts, và properties YAML ở đầu file. Hầu hết người dùng Obsidian sẽ cần skill này nhất.
• obsidian-bases - Dạy agent tạo và sửa file .base. Bases biến YAML properties của notes thành bảng dữ liệu có thể lọc và tính toán mà không cần viết query language. Skill này dạy agent cú pháp filter, công thức và cấu hình view.
• json-canvas - Dạy agent tạo file .canvas - bảng whiteboard dạng sơ đồ tư duy trong Obsidian. JSON Canvas là open format do chính Obsidian tạo ra tại jsoncanvas.org. Skill dạy agent cách thêm node, kéo mũi tên, nhóm ý và liên kết note vào canvas.
• obsidian-cli - Cho agent khả năng điều khiển vault qua dòng lệnh, bao gồm cả hỗ trợ phát triển plugin và theme Obsidian. Phù hợp với developer muốn tự động hóa tác vụ vault management.
• defuddle - Tool cũng của chính Steph Ango. Defuddle extract nội dung chính của bất kỳ trang web nào thành Markdown sạch, bỏ hết sidebar, menu, quảng cáo và phần rác khác. Agent chỉ đọc đúng phần nội dung cần thiết - tiết kiệm đến khoảng 80% token khi xử lý tài liệu online, bài viết, hay trang docs.

Chuẩn mở - một skill, nhiều agent

Điểm then chốt của bộ này là không lock vào một công cụ cụ thể. obsidian-skills theo chuẩn Agent Skills specification - mỗi skill chỉ là một folder với SKILL.md chứa hướng dẫn Markdown thuần. Không binary, không extension.

README của repo liệt kê tường minh: Claude Code, Codex CLI, và OpenCode. Nhưng bất kỳ agent nào hỗ trợ chuẩn Agent Skills đều dùng được - Gemini CLI, GitHub Copilot (VS Code) và nhiều community tool khác. Agent Skills specification được adopt rất nhanh sau khi Anthropic công bố: Microsoft và OpenAI đưa hỗ trợ vào tool của mình chỉ trong 48 giờ.

Điều này có nghĩa là người dùng không cần lo về "nếu mai này đổi tool". Cài một lần, dùng được trên nhiều agent khác nhau.

Cài đặt như thế nào

Có 3 cách tùy agent đang dùng:

Cách nhanh nhất - dùng npx (hoạt động với hầu hết agent):

npx skills add https://github.com/kepano/obsidian-skills

Với Claude Code - copy toàn bộ nội dung repo vào thư mục .claude/ trong root của Obsidian vault. Claude Code tự nhận diện các SKILL.md file trong .claude/skills/. Hướng dẫn chính thức có trong tài liệu Agent Skills của Anthropic.

Với OpenCode - clone cả repo vào ~/.opencode/skills/:

git clone https://github.com/kepano/obsidian-skills ~/.opencode/skills/obsidian-skills

Lưu ý: clone cả repo, không chỉ copy thư mục skills/ bên trong. OpenCode cần cấu trúc đúng để tự discover skill.

Với Codex CLI - copy thư mục skills/ vào ~/.codex/skills/. Chi tiết đầy đủ cho từng tool có trong README của repo.

Ai nên dùng ngay

obsidian-skills hữu ích nhất với những nhóm sau:

• Người dùng Obsidian đang xây "bộ não thứ hai" và muốn AI agent viết hay sắp xếp ghi chú đúng format
• Developer plugin hoặc theme Obsidian muốn dùng Claude Code để tự động hóa tác vụ vault
• Researcher muốn agent tự import bài viết từ web vào vault dưới dạng Markdown sạch - defuddle đặc biệt hữu ích ở đây
• Power user Bases muốn agent tạo hoặc cập nhật database view từ properties ghi chú
• Bất kỳ ai muốn kết hợp Obsidian với Claude Code, Codex CLI, OpenCode hoặc Gemini CLI

Với người chưa dùng Bases hay Canvas: obsidian-markdown là điểm khởi đầu hợp lý nhất - cài skill đó trước, test với vault thực, rồi mở rộng thêm skill khác khi cần.

Kết

obsidian-skills đặt ra một precedent thú vị: khi chính tác giả thiết kế một tool tự tay viết skill dạy AI dùng tool đó, chất lượng hướng dẫn ở cấp độ khác hoàn toàn so với community wiki hay blog hướng dẫn. Không phải đoán từ docs, mà là người biết rõ nhất hệ thống viết thẳng "đây là cách làm đúng".

Với người dùng Obsidian đang xây "bộ não thứ hai", đây là mảnh ghép quan trọng để AI agent làm việc được trong vault mà không phá vỡ cấu trúc đã dày công xây dựng. Wikilink không bị chuyển thành hyperlink thường. Bases không bị viết sai format. Canvas không thành file rỗng.

via kepano/obsidian-skills trên GitHub