Obsidian AI技能规范：从AI乱写到安全协作的标准化实践

1. 从“AI乱写”到“AI协作”：为什么你的Obsidian需要技能规范

最近在折腾AI Agent的朋友，估计都遇到过同一个头疼的问题：让AI帮你整理笔记、生成内容，结果它一通操作猛如虎，回头一看，你的Obsidian知识库（Vault）结构被改得面目全非，文件命名乱七八糟，甚至把一些核心的笔记链接给覆盖或删除了。这感觉就像请了个“破坏王”管家，本意是让它帮忙收拾屋子，结果它把家具全扔了，还在墙上涂鸦。

这正是Obsidian CEO亲自下场，推出obsidian-skills这个项目要解决的核心痛点。它不是一个新插件，也不是一个具体的AI工具，而是一套格式规范。你可以把它理解为给AI Agent制定的“Obsidian操作手册”或“安全驾驶指南”。它的目标很明确：让AI在理解你的知识库结构、遵循你的操作习惯的前提下，安全、可控、可预测地与你协作，而不是横冲直撞地搞破坏。

为什么这件事由Obsidian官方来推动，并且CEO亲自撰写规范？这背后反映了一个更深层的趋势：随着AI能力从“聊天”走向“行动”，从“生成文本”走向“操作环境”，我们需要一套标准化的“接口”和“协议”来确保人机协作的顺畅与安全。obsidian-skills就是为Obsidian这个高度个人化、结构敏感的知识管理环境，定义了一套AI可以理解和执行的行动标准。

简单来说，它回答了三个关键问题：

1. AI能做什么？(Skill的定义与描述)
2. AI怎么做？(Skill的输入、输出与执行流程)
3. 如何保证安全可控？(权限、验证与错误处理)

接下来，我们就深入拆解这套规范，看看它是如何设计，以及我们如何利用它来构建真正“听话”的AI助手。

2. 核心概念拆解：Skill、Agent与你的Vault

在深入规范细节前，我们需要厘清几个容易混淆的概念，这也是很多人在接触AI Agent时感到困惑的地方。结合网络热词中的疑问，比如“skill到底是什么？它和agent是什么关系”，我们来一次彻底的梳理。

2.1 Skill：AI的“可复用工具包”

你可以把Skill理解为AI Agent的“瑞士军刀”中的一把具体工具，比如“开瓶器”、“小刀”或“剪刀”。在obsidian-skills的语境下，一个Skill就是一个定义清晰、功能单一的操作单元。它明确规定了：

• 功能描述：这个Skill是干什么的？例如，“在指定文件夹中创建一个新的Markdown笔记”。
• 输入参数：执行这个操作需要哪些信息？例如，需要folder_path（文件夹路径）和note_title（笔记标题）。
• 输出结果：操作完成后会返回什么？例如，返回新创建笔记的完整文件路径。
• 执行逻辑：背后调用了Obsidian的哪些API或系统命令？这部分对AI是“黑盒”，AI只需要知道如何调用它。

一个关键类比：Skill就像编程中的“函数”。你定义好函数名、参数和返回值，调用者（AI）不需要关心函数内部是如何实现的，只需要按照约定传入正确的参数，就能得到预期的结果。这极大地降低了AI操作的复杂度和不确定性。

2.2 Agent：Skill的“调度员与决策者”

Agent则是那个拿着“瑞士军刀”的人。它具备理解你的自然语言指令、分析当前上下文（比如你正在浏览哪个笔记、知识库的总体结构）、并决定调用哪一把“工具”（Skill）来完成任务的能力。

• 关系：一个Agent可以拥有并调用多个Skills。例如，一个“笔记管理Agent”可能集成了“创建笔记”、“搜索笔记”、“更新笔记元数据”、“建立笔记链接”等多个Skills。
• 与MCP的区别：网络热词中提到了“Agent Skill 和 MCP 有什么区别”。MCP（Model Context Protocol）是另一个由Anthropic等公司推动的协议，旨在为AI模型提供访问工具和数据源的标准化方式。你可以把obsidian-skills看作是Obsidian领域的、具体化的MCP实现。MCP是更通用的“工具调用协议”，而obsidian-skills是利用类似思想，专门为Obsidian生态定制的“技能规范”。它更垂直，定义的操作直接映射到Obsidian的核心对象（文件、链接、标签、图谱等）。

2.3 Vault：需要被尊重的“私人领域”

你的Obsidian Vault（知识库）不是一个普通的文件夹，它是一个充满内部关联（双向链接）、元数据（Frontmatter）、特定插件配置和个性化工作流的复杂系统。AI的“破坏性”往往源于它用处理普通文本文件的方式来处理Vault，忽略了这些隐性的结构和约定。

obsidian-skills规范的核心精神之一，就是引导AI将Vault视为一个有状态的、结构化的领域模型来操作，而不是一堆离散的.md文件。这意味着AI在执行“创建链接”这个Skill时，应该理解这不仅仅是在文本中插入一个[[链接]]，而是在知识图谱中建立一个新的关系节点。

3.obsidian-skills规范深度解析：如何定义一把好“工具”

了解了核心概念，我们来看规范本身。虽然项目正文可能比较简略，但结合其目标和社区讨论，我们可以还原出这套规范的关键组成部分。它本质上是一个JSON Schema，用于描述Skill。

3.1 Skill描述文件的结构

一个符合obsidian-skills规范的Skill，通常会通过一个描述文件（如skill.json）来声明自己。这个文件可能包含以下核心字段：

{ "name": "create_note", "description": "在指定的文件夹中创建一个新的Markdown笔记。如果文件夹不存在，会先创建它。", "version": "1.0.0", "author": "Your Name", "input_schema": { "type": "object", "properties": { "folder_path": { "type": "string", "description": "笔记将要创建到的文件夹路径，相对于Vault根目录。例如：'Projects/Research'。" }, "note_title": { "type": "string", "description": "新笔记的标题。这将用于生成文件名（会进行安全字符处理）和笔记内的一级标题。" }, "initial_content": { "type": "string", "description": "笔记的初始Markdown内容。可选，默认为空。", "default": "" } }, "required": ["folder_path", "note_title"] }, "output_schema": { "type": "object", "properties": { "success": { "type": "boolean", "description": "操作是否成功。" }, "created_file_path": { "type": "string", "description": "新创建笔记的完整Vault内部路径。例如：'Projects/Research/My New Note.md'。" }, "error_message": { "type": "string", "description": "如果失败，此处包含错误信息。" } } }, "permissions": ["vault:write", "file:create"] }

逐字段解读与设计理由：

1. name&description：这是Skill的“身份证”和“说明书”。清晰、准确的描述对于AI理解何时调用该Skill至关重要。描述应使用自然语言，说明功能、适用场景和潜在副作用。
2. input_schema：这是规范的重中之重。它使用JSON Schema严格定义了调用此Skill必须提供哪些参数，每个参数的类型、格式、描述和是否必填。
   • 为什么需要严格模式？防止AI“想当然”。如果没有明确约束，AI可能会传入一个不存在的文件夹路径，或者包含非法字符的文件名，导致操作失败或产生意外文件。严格的Schema让AI的调用行为变得可预测、可验证。
   • description字段的价值：它为AI（大语言模型）提供了理解参数含义的上下文，是实现准确调用的关键。
3. output_schema：定义了Skill执行后的返回格式。统一的输出格式让Agent能够以标准化的方式处理所有Skill的结果，无论是用于后续步骤的判断，还是展示给用户。
   • 包含success和error_message：这是健壮性设计。任何操作都可能失败，明确的成功/失败标识和错误信息，能让Agent进行有效的错误处理和用户反馈。
4. permissions：安全性的核心。它声明了这个Skill需要哪些权限。例如：
   • vault:read：仅读取文件内容。
   • vault:write：修改或创建文件。
   • plugin:xxx：调用特定插件的API。
   • system：执行系统级命令（此权限应极其谨慎）。
   • 设计意图：用户或Vault的管理员可以在授权AI Agent运行时，基于Skill声明的权限进行“最小权限”授予。一个只负责摘要笔记的Agent，可能只获得vault:read权限，从根本上杜绝其“破坏”的可能性。

3.2 规范如何防止“Vault破坏”

基于上述结构，规范从多个层面构建了防护网：

1. 路径安全：通过input_schema约束，Skill可以要求folder_path必须是Vault内的相对路径，防止AI尝试写入系统目录。执行Skill的底层实现代码会进行路径规范化（path.normalize）和边界检查。
2. 文件命名安全：在实现“创建笔记”Skill时，底层逻辑应自动处理标题中的特殊字符（如\ / : * ? " < > |），将其转换为安全的文件名（如用-代替:），避免创建出操作系统无法处理的文件。
3. 操作原子性与回滚：一个设计良好的Skill应该是原子的。复杂的操作（如“移动并重新链接所有相关笔记”）应由多个原子Skill组合完成，或在Skill内部实现事务性。虽然规范本身不强制，但它鼓励这种设计思维，并为每个Skill定义清晰的输入输出，使得组合和错误恢复成为可能。
4. 权限隔离：这是最根本的防护。一个只有读取权限的Agent，无论它的指令多么危险，也无法执行删除或覆盖操作。

实操心得：从“黑盒”到“白盒”的转变在没有规范之前，我们给AI的指令是：“帮我在‘Projects’文件夹下创建一个关于‘AI Agent规范’的笔记，内容大纲是...”。这是一个“黑盒”请求，AI会用自己的方式（可能是调用某个不熟悉的API，或用字符串拼接直接写文件）来完成，结果不可控。 有了规范后，指令变成了：“请调用create_note技能，参数为{folder_path: 'Projects', note_title: 'AI Agent规范研究', initial_content: '...'}”。这是一个“白盒”请求，我们和AI都明确知道即将发生什么，以及如何发生。这种可预测性，正是人机可靠协作的基础。

4. 实战：基于规范构建你的第一个Obsidian AI Skill

理论讲完了，我们来点实际的。假设我们要实现上面提到的create_noteSkill。这里不涉及具体的AI Agent框架（如LangChain、AutoGen），而是聚焦于Skill本身的实现，这是规范落地的关键。

4.1 环境准备与项目结构

首先，你需要一个地方来开发和管理你的Skills。建议在Obsidian Vault之外创建一个独立的项目文件夹。

my-obsidian-skills/ ├── package.json # 项目描述和依赖 ├── skills/ # 存放所有Skill的实现 │ └── create-note/ │ ├── skill.json # Skill的描述文件（如上文示例） │ ├── index.js # Skill的核心实现逻辑 │ └── README.md # 给开发者看的说明 └── server.js # 一个简单的Skill服务端（可选，用于被Agent调用）

为什么需要独立的项目？因为Skill的实现可能涉及Node.js环境、第三方库，这些不应该污染你的Obsidian Vault。Skill通过某种服务端（如HTTP、WebSocket）或插件形式暴露给Obsidian和AI Agent。

4.2 实现create_noteSkill的核心逻辑

skills/create-note/index.js文件是Skill的执行体。它需要做以下几件事：

1. 解析输入：接收来自Agent的、符合input_schema的JSON参数。
2. 验证与安全处理：检查路径是否在Vault内，处理文件名。
3. 调用Obsidian API：通过某种方式与Obsidian交互。这里有两种主流方式：
   • 方式A：通过Obsidian插件API（推荐）：将你的Skill打包成一个Obsidian插件。这样可以直接、安全地使用Obsidian内置的所有API。
   • 方式B：通过外部进程通信：运行一个本地服务，通过Obsidian的命令行接口或社区插件（如Advanced URI或Execute Code）进行交互。这种方式更灵活，但复杂度更高。
4. 返回标准输出：按照output_schema的格式返回结果。

以下是一个简化的、基于Node.js的示例逻辑（假设通过文件系统直接操作Vault，注意：这需要谨慎处理路径和文件锁）：

const fs = require('fs').promises; const path = require('path'); /** * create_note Skill 的实现函数 * @param {Object} params - 符合input_schema的输入对象 * @param {string} params.folder_path - 目标文件夹路径 * @param {string} params.note_title - 笔记标题 * @param {string} params.initial_content - 初始内容 * @param {string} vaultRoot - Obsidian Vault的绝对路径 * @returns {Promise<Object>} - 符合output_schema的输出对象 */ async function createNote(params, vaultRoot) { const { folder_path, note_title, initial_content = '' } = params; try { // 1. 安全处理：构建绝对路径并确保在Vault内 const safeTitle = note_title.replace(/[\\/:*?"<>|]/g, '-'); const targetDir = path.resolve(vaultRoot, folder_path); const filePath = path.join(targetDir, `${safeTitle}.md`); // 简单的路径遍历检查 if (!filePath.startsWith(path.resolve(vaultRoot))) { throw new Error('Attempted to write outside vault boundary.'); } // 2. 确保目录存在 await fs.mkdir(targetDir, { recursive: true }); // 3. 构建文件内容（可加入YAML Frontmatter等） const fileContent = `# ${note_title}\n\n${initial_content}`; // 4. 写入文件（考虑文件是否已存在，这里选择覆盖，可根据需求修改） await fs.writeFile(filePath, fileContent, 'utf8'); // 5. 返回成功结果 const relativePath = path.relative(vaultRoot, filePath).replace(/\\/g, '/'); // 统一为正斜杠 return { success: true, created_file_path: relativePath, error_message: null }; } catch (error) { // 6. 返回失败结果 console.error(`create_note skill failed:`, error); return { success: false, created_file_path: null, error_message: error.message }; } } module.exports = createNote;

注意事项与避坑指南：

• 文件锁与并发：如果多个AI Agent或进程同时操作同一个Vault，直接写文件可能引发冲突。在生产环境中，需要考虑通过队列或锁机制来管理写操作。Obsidian插件环境在这方面有更好的保障。
• Obsidian元数据：真正的笔记创建往往需要处理Frontmatter（如tags、aliases、created日期）。一个更完善的Skill应该允许通过input_schema传入这些元数据，并在生成文件时正确格式化。
• 链接更新：创建新笔记后，是否要自动更新其他笔记中的链接？这属于另一个Skill（如update_references）的范畴，保持单一职责。
• 错误处理粒度：上面的示例错误处理比较粗略。更好的做法是根据错误类型（如权限错误、路径错误、磁盘已满）返回更具体的错误码，方便Agent采取不同策略。

4.3 将Skill暴露给AI Agent

实现好Skill后，你需要一个“桥梁”让AI Agent发现并调用它。常见模式是构建一个Skill服务端。

1. 注册Skill：服务启动时，读取所有skill.json文件，构建一个Skill清单。
2. 提供发现接口：暴露一个API端点（如GET /skills），返回所有可用的Skill及其描述和输入模式。AI Agent在初始化时会查询这个列表。
3. 提供执行接口：暴露另一个API端点（如POST /skills/:name/execute），接收Skill名和参数，调用对应的实现函数，并返回结果。

这样，任何兼容的AI Agent框架，只要知道你这个服务端的地址，就能通过HTTP请求来调用这些Skills。这就是MCP等协议的基本思想。

5. 设计模式与最佳实践：构建健壮的Skill体系

当你开始设计多个Skills时，就需要考虑它们之间的协作和整个体系的可维护性。以下是一些从软件工程中借鉴的最佳实践：

5.1 Skill的单一职责与组合模式

一个Skill只做好一件事。不要设计一个“超级Skill”叫process_and_organize_notes。应该拆分成：

• search_notes_by_tag
• extract_summary_from_note
• create_note(已有)
• append_to_note
• add_link_between_notes

AI Agent（或一个编排层）负责将这些原子Skill组合起来完成复杂任务。这带来了极大的灵活性和可复用性。

5.2 输入验证与默认值

在Skill的实现内部，必须对输入进行二次验证，即使Schema已经定义。因为调用方（AI）可能出错。对于可选参数，提供合理的默认值。例如，initial_content默认为空字符串。

5.3 幂等性与安全重试

尽可能让Skill的操作是幂等的。即，用相同的参数重复调用，产生的效果应该和只调用一次相同。例如，create_note在文件已存在时，可以选择“跳过”、“覆盖”或“创建副本并重命名”。在Schema或Skill描述中明确说明这种行为，有助于Agent进行错误恢复和重试。

5.4 提供丰富的上下文信息

在skill.json的description字段和参数的description字段中，尽可能详细地说明使用场景、限制和副作用。这些描述会被AI模型读取，是它决定是否以及如何调用该Skill的主要依据。好的描述本身就是一种“提示工程”。

5.5 版本管理

Skill的version字段很重要。当Skill的实现逻辑或输入输出Schema发生变化时（尤其是破坏性变更），必须升级版本号。这允许Agent或用户端知道他们正在调用的是哪个版本的Skill，避免兼容性问题。

6. 展望：obsidian-skills生态与未来工作流

obsidian-skills规范的价值，不仅在于防止破坏，更在于开启了Obsidian自动化与智能化的新篇章。我们可以预见几个发展方向：

1. Skill市场/仓库：像Obsidian插件社区一样，会出现一个共享Skill的仓库。你可以下载一个“学术文献管理Skill包”，里面包含从Zotero导入、生成文献笔记、自动链接相关论文等一系列Skills，直接集成到你的AI Agent中。
2. 可视化Skill编排工具：可能会出现类似IFTTT或n8n的低代码工具，让你通过拖拽的方式，将不同的Skill组合成自动化工作流（例如：“当每日日志笔记创建时，自动调用fetch_weatherSkill获取天气，并调用append_to_noteSkill写入”）。
3. 更细粒度的权限与审计：权限系统可以发展到针对单个文件、特定标签的笔记进行授权。并且，所有AI对Vault的操作都可以被详细记录（审计日志），方便回溯和撤销。
4. 与LLM Wiki等工具的深度集成：网络热词中提到了“llmwiki 与obsidian如何搭配”。obsidian-skills可以为这类工具提供标准化的操作接口，让它们能更安全、更丰富地与你的知识库互动，例如，让LLM Wiki不仅能读取，还能按照规范帮你整理和重构笔记结构。

个人体会与最后建议

我尝试基于早期思路实现过几个自定义的“准Skill”，最大的感受是：规范性带来的心智负担降低是巨大的。以前每次让AI操作笔记都提心吊胆，需要反复检查备份。现在，只要Skill描述清晰、权限得当，我可以很放心地将一些重复性工作交给Agent。

对于想要尝鲜的开发者，我的建议是：不要一开始就想着造一个全能的Agent。从解决一个具体的、高频的痛点开始。比如，先实现一个archive_daily_noteSkill，它负责将昨天的每日笔记移动到“Archives/Daily”文件夹，并更新其Frontmatter中的status为archived。把这个单一的Skill做稳定、做可靠，你就能深刻理解输入验证、错误处理和权限控制的重要性。然后，再逐步扩展你的Skill工具箱。

obsidian-skills与其说是一个成品，不如说是一个倡议和蓝图。它标志着Obsidian生态从“人机交互”正式迈向“人机协作”。通过定义清晰的边界和协议，它让我们既能享受AI带来的自动化红利，又能牢牢守住个人知识圣殿的自主权和完整性。这或许是所有复杂工具在AI时代走向成熟的必经之路。