Connecting AI to Obsidian: An Open-Source Four-Layer Skeleton and Four Skills

If you use Obsidian to manage knowledge but always feel like AI is an outsider—only able to be fed through your copy-pasting—then an Agent skeleton open-sourced by Bilibili creator "Whale Miss" (鲸鱼大小姐) might change that awkwardness. This solution isn't a plugin, nor a template, but a structural specification that draws boundaries for AI: a four-layer vault and four skills, all open source under the MIT license.

Four-Layer Vault: Drawing Clear Boundaries for the Agent

The core idea of this skeleton is to divide the Obsidian vault into four layers, each with an explicit definition of "who can write and what they can write," and to document these rules. Crossing the boundary is treated as a fault.

• Knowledge layer: Written by humans, one concept per file. This is where humans accumulate knowledge; AI does not modify it directly.
• Kanban layer: Read-only, for AI to understand task status.
• Skills layer: Rules for the Agent to read, defining what it can and cannot do.
• Log layer: Append-only, no overwriting allowed. This comes from a painful lesson—the creator once tried an automated flow that overwrote an entire log with a model response. Although it has been fixed, logs are henceforth append-only.

This layered design is essentially about using engineering means to constrain AI's behavioral boundaries when it intervenes in knowledge management. According to the creator, the knowledge layer is packaged according to Google's OKF specification: one concept per file, with type and timestamp, one package per course, with an index and a log. The index handles progressive disclosure, and the log is append-only. The benefit is tangible: if you can cat it, you can read it.

Google OKF Specification (Open Knowledge Format) is an open format proposed by Google for knowledge management, emphasizing organizing knowledge as "one concept per file," with each file containing metadata such as type and timestamp, and progressive disclosure through an index. Its biggest difference from traditional note stacking is auditability: any tool (including an AI Agent) can understand the knowledge structure by reading the index and file contents, without parsing complex databases or proprietary formats. OKF's design goal is to make the knowledge base versionable, diffable, and automatable like a code repository, which aligns closely with the philosophy in this article that "if you can cat it, you can read it."

Four Skills: From Organizing to Quiz Practice

Once the skeleton is built, the Agent truly has AI integrated. The creator designed four practical skills, each with clear boundaries and operational specifications.

Daily Organization: Three-Tier Classification, Conservative Handling

This skill classifies issues into three tiers: mechanical items (missing characters, incorrect date formats) are fixed directly; semantic items (should this page be split?) are first reported to an "improvement area"; the original text and evidence of conclusions are not touched at all. If unsure whether it's A or B, treat it as B—the more conservative tier. This cautious design stems from the aforementioned log overwriting incident.

Deadlines: A Guessed DDL Is More Dangerous Than None

The second skill handles deadlines. The creator's principle is clear: a guessed DDL is more dangerous than none, because it makes you think you're already overdue. So only officially published normal deadlines are taken; late do is recorded separately and never written into deadline. Each entry is tagged with its source: published, converted, or inferred. A diff is generated before writing, and it's only committed after manual confirmation.

Quiz Practice: Judge Only, Don't Do the Work

The third skill is quiz practice. Scoring must pinpoint the first error; wrong answers are stored, and before exams only previously wrong questions plus variations on the same concept are surfaced. This skill doesn't do the questions for the user; it only scores and organizes wrong answers, with clear boundaries.

Courseware Conversion: PDF to Structured Lecture Notes

The fourth skill is courseware conversion. A PDF comes in and becomes structured lecture notes: all formulas in LaTeX, English courseware paired with Chinese, artistic headers/footers and decorative images removed, and homework assignments set in a separate section.

LaTeX is a typesetting system particularly strong at formula typesetting, widely used in academia and engineering. Converting formulas from PDF to LaTeX means formulas go from "uneditable images or glyphs" to "searchable, modifiable text code," which is crucial for knowledge management and subsequent AI processing. For example, an integral formula in a PDF is just a visual symbol, but once converted to LaTeX, an Agent can understand its structure, extract variables, and even generate variation problems. This is also the core reason the courseware conversion skill chooses LaTeX over retaining original images: computability takes priority over visual fidelity.

A 70,000-Byte Specification, Not a Program

The most distinctive aspect of this solution is that it is a specification of over 70,000 bytes, not a piece of software. The creator emphasizes that the knowledge layer is not just a random pile of notes, but a skeleton packaged according to the Google OKF specification. Five packages, 228 pages of documentation—how to prove it's not a toy? Three sets of offline tests—nine items, five items, sixty-four items—run through CI on every push. There isn't a single real course name in the repository, and the demo GIFs are from real terminal runs.

The workflow has three steps: clone the repository, export the Vault path, and run the health check. The first step is read-only and makes no changes; any file operation requires explicitly adding apply. The creator also candidly acknowledges limitations: the browser pipeline hasn't been tested, screenshot recognition only supports macOS, and there's no built-in rollback. A course's checklist is written in json, not in code—to switch to your own vault, just change one configuration.

CI (Continuous Integration) is a software development practice where tests and build processes run automatically after each code push to catch integration errors early. The "CI runs the full suite on every push" mentioned in the article means this specification repository has an automated pipeline configured, where three sets of offline tests (nine items, five items, sixty-four items) run automatically on each commit, ensuring consistency between specification documents and accompanying scripts. For a specification that is "not a program," the existence of CI is a credibility endorsement: it proves this structure is not a one-time static document, but a living specification continuously validated and maintained like software.

Openness and Limitations

This skeleton uses the MIT license—star it if useful, or give feedback in issues if not. It represents an approach: integrating AI into knowledge management tools doesn't have to be a plugin or template; it can also be a specification that constrains Agent behavior. For Obsidian users, this may be a starting point worth trying—provided you can accept its conservative design and current limitations.

One-line Summary

An open-source Agent skeleton uses a four-layer vault and four skills to draw behavioral boundaries for AI in Obsidian.

Paragraph Summary

Bilibili creator "Whale Miss" open-sourced an Agent skeleton for Obsidian under the MIT license. Its core is not a plugin or template, but a 70,000-byte structural specification: the vault is divided into a knowledge layer (human-written), kanban layer (read-only), skills layer (Agent rules), and log layer (append-only), with each layer's "who can write and what" explicitly defined—crossing the boundary is treated as a fault. On this foundation, four practical skills are designed—daily organization (three-tier classification with conservative handling), deadlines (only officially published DDLs with source tags), quiz practice (judge only, don't do the work), and courseware conversion (PDF to structured LaTeX lecture notes). The knowledge layer is packaged per the Google OKF specification, with accompanying offline tests and CI validation. The solution emphasizes auditability and conservative design, but has limitations: the browser pipeline is untested, screenshot recognition is macOS-only, and there's no built-in rollback.