obsidian-skills 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

obsidian-skills 是一组面向 Obsidian 工作流的智能体技能（Agent Skills），用于指导兼容智能体处理 Obsidian Markdown、Bases、JSON Canvas，并通过 Obsidian CLI 操作仓库。它遵循 Agent Skills 规范，可供 Claude Code、Codex 和 OpenCode 等兼容客户端加载。

• 仓库状态：默认分支为 main；GitHub 元信息显示 Star 为 48,601、Fork 为 3,463，该数字是给定资料的快照，不代表实时数据。
• 主要能力：编辑 Obsidian 风格 Markdown、Bases 与 JSON Canvas，调用 Obsidian CLI，清理网页正文，以及基于 JSON 或 CSV 批量渲染 Markdown 模板。
• 集成方式：支持 Marketplace 命令、npx skills、Claude Code 手动安装、Codex 技能目录和 OpenCode 技能目录。
• 许可证：MIT，可用于商业项目，但复制或分发软件及其重要部分时需要保留版权声明和许可文本。
• 需要注意：该仓库提供的是技能定义，不是独立运行的 Obsidian 替代品。官方仓库未提供版本号、运行端口、环境变量、性能基准、服务等级协议或独立服务端部署说明。

“Agent Skills for use with Obsidian.”

“These skills follow the Agent Skills specification so they can be used by any skills-compatible agent, including Claude Code, Codex, and Open Code.”

定位与目标用户

该项目的定位是为智能体提供 Obsidian 相关操作知识和文件格式约束，而不是提供新的笔记客户端、同步服务或模型服务。使用者需要先拥有一个支持 Agent Skills 规范的宿主工具，再将仓库中的技能加载到宿主环境。

这里的“技能”可以理解为供智能体读取的任务说明和格式规范。根据 README，兼容对象包括 Claude Code、Codex 和 OpenCode；其他工具是否兼容，取决于其是否实现 Agent Skills 规范。

项目主要面向维护 Obsidian 仓库的个人或团队，以及需要让编码智能体生成开放格式文件的开发者。它也适用于插件和主题开发工作流，但具体支持范围受 Obsidian CLI 能力及对应技能内容约束。

核心功能与能力边界

仓库当前列出六项技能，每项技能负责一个相对独立的输入、处理规则和输出格式。README 没有给出技能选择算法，因此何时自动触发、是否需要用户显式指定技能，应以宿主智能体的实现和最新技能文件为准。

Obsidian 风格 Markdown

obsidian-markdown 面向 .md 文件，覆盖双向链接（wikilinks）、嵌入、标注块（callouts）、属性以及其他 Obsidian 专用语法。它的作用不是发明新的文本格式，而是让智能体在生成或编辑文件时遵守 Obsidian Flavored Markdown 的规则。

触发条件由所使用的兼容智能体决定；README 未提供固定触发关键词。输入是用户的笔记创建或编辑要求，输出是可保存到 Obsidian 仓库中的 Markdown 内容，准确性依赖技能文件和宿主智能体对指令的执行。

Obsidian Bases

obsidian-bases 用于创建和编辑 .base 文件，覆盖视图、筛选器、公式与汇总。其工作机制是向智能体提供 Obsidian Bases 语法相关约束，再由智能体根据数据组织需求生成对应文本文件。

输入可以是期望展示的字段、筛选逻辑和汇总目标，输出是 Bases 文件内容。README 没有提供字段类型清单、公式函数清单或完整示例，因此涉及具体语法时应核对 Obsidian 官方文档和仓库内最新的 SKILL.md。

JSON Canvas

json-canvas 面向 .canvas 文件，可描述节点、边、分组及连接。技能依赖开放的 JSON Canvas 格式，输出应当是符合该格式的数据文件，而不是截图或封闭的二进制画布。

用户提供画布结构或关系要求后，智能体负责形成节点和连接数据。节点字段、坐标规则和格式校验细节未包含在给定 README 摘要中，官方仓库未提供该信息，建议以最新技能文件和 JSON Canvas 规范为准。

Obsidian CLI

obsidian-cli 用于通过 Obsidian CLI 与 Obsidian 仓库交互，并覆盖插件和主题开发相关任务。该技能提供操作指导，但底层命令仍由 Obsidian CLI 执行。

输入是针对仓库、插件或主题的操作意图，输出是宿主执行 CLI 后产生的结果。README 没有列出具体 CLI 子命令、Obsidian 版本要求或错误码，因此不应依据本项目描述推断任何未展示的命令参数。

Defuddle 网页正文提取

defuddle 使用 Defuddle 从网页提取清理后的 Markdown，并移除页面杂项以减少传入智能体的文本量。它接收网页内容并输出更聚焦的正文，而不是保存完整网页副本。

网页获取方式、网络请求参数、登录态处理和站点兼容范围没有出现在给定资料中。涉及受访问控制保护的网页时，必须先确认访问授权，不应使用该技能规避身份验证、付费访问或站点限制。

Knap 模板渲染

knap 使用 Knap 将 JSON 或 CSV 数据渲染到 Markdown 模板中，并支持批量生成文件。其输入包括模板和结构化数据，输出是渲染完成的 Markdown 文件集合。

README 未提供模板占位符语法、字段映射规则和冲突处理策略。使用前应检查 Knap 文档及本仓库对应技能，避免根据未验证的模板语法批量覆盖笔记。

系统架构与关键模块

从 README 可确认的结构由“兼容智能体、技能目录、外部格式或工具、Obsidian 仓库”四部分组成。项目本身没有被描述为常驻服务，也没有给出 HTTP API、数据库或消息队列。

1. 宿主层：Claude Code、Codex、OpenCode 或其他兼容 Agent Skills 规范的智能体负责发现并读取技能。
2. 技能层：仓库的 skills/ 目录包含各技能，OpenCode 所需结构明确为 ~/.opencode/skills/obsidian-skills/skills/<skill-name>/SKILL.md。
3. 格式与工具层：技能分别面向 Markdown、Bases、JSON Canvas、Obsidian CLI、Defuddle 和 Knap。
4. 数据层：最终内容写入或作用于 Obsidian 仓库；具体写入动作由宿主和底层工具完成。

根据本文作者的经验判断，这种架构的关键控制点是技能发现路径和文件写入权限，而不是网络端口。该判断用于帮助部署决策，并非 README 对内部实现的正式说明。

依赖与运行环境

运行环境取决于选择的安装方式，至少需要一个兼容 Agent Skills 的宿主。官方仓库未给出操作系统范围、Node.js 版本、npm 版本、Obsidian 版本或硬件要求，建议以最新 README 为准。

• Marketplace 方式：需要支持 README 所列 Marketplace 命令的宿主，具体宿主名称和版本未提供。
• npx skills 方式：需要能够执行 npx，但 README 未规定 Node.js 与 npx 的最低版本。
• Claude Code：将仓库内容放入 Obsidian 仓库根目录下的 /.claude 文件夹，或放入 Claude Code 正在使用的其他目录。
• Codex：将 skills/ 目录复制到 Codex 技能路径，README 给出的典型路径是 ~/.codex/skills。
• OpenCode：将完整仓库克隆到 ~/.opencode/skills/obsidian-skills，不能只复制内部 skills/ 目录。

仓库语言在给定 GitHub 元信息中标记为“未知”。资料未提供 package.json、pyproject.toml、容器镜像、Compose 文件或锁文件，因此不能据此列出确定的运行时依赖版本。

快速开始：安装、运行与验证

OpenCode 路径提供了最清晰的目录约束，可用于建立一个本地安装闭环。安装后必须重启 OpenCode，README 明确说明重启后技能才会变为可用状态。

方案一：使用 OpenCode

以下克隆命令直接来自 README。验证命令使用本地 Shell 的 test 检查 README 明确给出的文件路径，不会发起额外网络请求，也不会修改 Obsidian 仓库。

# 安装：克隆完整仓库，不要只复制内部 skills/ 目录
git clone https://github.com/kepano/obsidian-skills.git ~/.opencode/skills/obsidian-skills

# 运行：完成克隆后重启 OpenCode
# README 未提供 OpenCode 的命令行启动或重启命令

# 验证目录结构中至少存在一个 README 所述的 SKILL.md
test -f ~/.opencode/skills/obsidian-skills/skills/obsidian-markdown/SKILL.md && \
  printf '%s\n' 'obsidian-markdown skill found'

文件检查通过仅能证明技能文件位于预期路径，不能证明宿主已经完成解析。重启 OpenCode 后，还应在宿主内确认技能已被自动发现；README 没有提供用于列出已加载技能的命令，因此验证界面和具体操作以 OpenCode 当前版本为准。

方案二：使用 npx skills

README 同时给出 SSH 和 HTTPS 两种仓库地址，二者是替代关系，不需要重复执行。若本机没有配置 GitHub SSH 凭据，应选择 HTTPS 命令。

# 使用 SSH 地址安装
npx skills add git@github.com:kepano/obsidian-skills.git

# 或使用 HTTPS 地址安装
npx skills add https://github.com/kepano/obsidian-skills

README 没有提供 npx skills 安装后的目标目录、启动命令和状态检查命令。安装成功后应按照对应宿主的技能加载流程运行和验证，缺失信息建议以最新 README 及 Agent Skills 规范为准。

方案三：使用 Marketplace

Marketplace 方式包含“添加市场源”和“安装插件”两个步骤。命令运行位置取决于提供该命令接口的宿主，README 没有给出终端类型或版本要求。

/plugin marketplace add kepano/obsidian-skills
/plugin install obsidian@obsidian-skills

这两条命令必须按顺序执行：先注册仓库，再安装名为 obsidian 的插件。安装后的加载提示、成功输出和验证命令未在资料中提供。

配置说明

给定资料没有环境变量、配置文件字段或服务端参数，不能构造不存在的配置项。实际配置重点是选择正确的安装范围和目录结构。

OpenCode 会自动发现 ~/.opencode/skills/ 下的所有 SKILL.md 文件，README 明确说明不需要修改 opencode.json 或其他配置文件。技能在重启 OpenCode 后可用，这是该安装方式中唯一明确给出的生效条件。

进阶用法与工作流组合

进阶价值来自多项技能的串联，而不是增加未公开的配置参数。以下组合是根据各技能输入与输出关系形成的工作流设计，具体调用语句和自动触发行为仍由宿主决定。

1. 网页归档：先由 defuddle 将已获授权访问的网页清理为 Markdown，再由 obsidian-markdown 补充 Obsidian 属性、双向链接或标注块。
2. 结构化批量制卡：以 JSON 或 CSV 作为数据源，通过 knap 渲染 Markdown 模板，再用 Markdown 技能检查 Obsidian 专用语法。
3. 笔记索引视图：让 obsidian-bases 根据已有笔记属性生成 .base 文件，用视图、筛选器和汇总组织内容。
4. 关系图表达：把明确的实体和关系转换为 JSON Canvas 节点与边，输出 .canvas 文件供 Obsidian 打开。
5. 开发任务：使用 obsidian-cli 技能辅助插件或主题开发，但只调用当前 Obsidian CLI 文档确认存在的命令。

批量写入前应在测试仓库或版本控制分支中检查生成结果。根据本文作者的经验判断，模板批量生成与画布坐标生成最容易产生大量变更，因此应先用少量非敏感样例验证；仓库资料未提供事务、回滚或冲突合并机制。

可观测性与运维

该项目没有公开独立的日志系统、指标接口、追踪协议或健康检查端点。运维重点应放在技能是否被发现、输出文件是否符合格式，以及宿主执行过程是否出现权限或路径错误。

• 安装检查：核对技能目录和 SKILL.md 是否位于宿主要求的位置。
• 加载检查：OpenCode 安装后需重启；Claude Code 和 Codex 的重新加载行为未在资料中说明。
• 输出检查：分别使用 Obsidian、Bases 或 JSON Canvas 对应工具打开生成文件，检查语法和结构。
• 变更审查：对 Markdown、.base 和 .canvas 文本进行差异审查，确认没有意外覆盖。
• 故障证据：保留宿主产生的错误信息，但日志路径、日志级别和保留周期由宿主决定，仓库未提供统一标准。

官方仓库未提供监控仪表盘、告警规则、备份方案、灾难恢复指标、吞吐量或并发数据。若团队需要这些运维能力，应在宿主和 Obsidian 仓库管理层单独设计，不能把技能仓库视为提供 SLA 的托管服务。

安全与合规边界

项目能够接触本地笔记、网页内容和批量数据文件，因此应把文件权限、隐私数据和外部内容授权作为主要边界。只应在自有或明确授权的 Obsidian 仓库、网页和数据集上使用这些技能。

• 最小权限：宿主只应获得完成任务所需的目录访问权，不应无条件开放整个主目录或无关项目目录。
• 敏感笔记：在把笔记交给宿主智能体处理前，应确认其数据处理方式符合组织的隐私与保密要求。README 未提供数据留存、模型传输或加密承诺。
• 网页提取：使用 Defuddle 时应遵守目标站点的访问条件、版权要求和适用法律，不应绕过登录、付费访问或技术限制。
• 批量写入：使用 Knap 或 CLI 生成大量文件前，应在隔离的测试仓库中验证，并为原始数据保留可恢复副本。
• 外部内容：根据本文作者的经验判断，网页和 CSV 中的文本应被视为不可信输入，不能因其出现在数据源中就授予命令执行或额外文件访问权限。

仓库没有提供安全审计报告、漏洞响应政策、CVE 列表、沙箱说明或合规认证。需要受监管数据处理、审计留痕或数据驻留承诺的组织，应自行完成评估，并以宿主工具及数据处理方的正式条款为准。

许可证与商用条款

仓库采用 MIT License，版权声明为“Copyright (c) 2026 Steph Ango (@kepano)”。MIT 条款允许使用、复制、修改、合并、发布、分发、再许可和销售软件副本，因此可用于商业项目。

许可的核心条件是：在软件的所有副本或重要部分中保留版权声明和许可声明。将技能复制到内部仓库、随产品分发或制作修改版时，不应删除这些文本。

软件按“原样”提供，不附带明示或默示担保，包括适销性、特定用途适用性和不侵权担保；作者或版权方不对因软件或其使用产生的索赔、损害或其他责任承担责任。涉及具体分发模式、第三方格式或依赖许可证时，应分别核对相应项目条款，最终以仓库 LICENSE 文件为准。

局限性与已知限制

现有资料足以确认技能范围和安装路径，但不足以评估生产级性能、稳定性与兼容矩阵。以下限制来自 README 未覆盖的信息，不能用推测补齐。

• 没有项目版本号、发行标签、变更日志或升级兼容承诺。
• 没有明确列出支持的 Obsidian、Claude Code、Codex、OpenCode、Node.js 或操作系统版本。
• 没有性能基准、最大文件数量、最大 Canvas 节点数、批处理规模或并发级别数据。
• 没有说明宿主如何选择技能、如何解决多个技能冲突，或如何禁止某项技能。
• 没有统一的运行命令、验证命令、回滚流程、测试套件说明或错误码清单。
• 没有说明 Defuddle 的网页兼容范围，也没有给出 Knap 模板语法示例。
• 没有提供独立 API、服务端端口、认证方式、环境变量和容器化部署方法。

这些空白不等同于功能缺失，只表示给定资料无法验证。需要依赖某项具体能力时，应直接检查默认分支中的技能文件和最新 README，而不是依据项目简介作出生产承诺。

适合谁／不适合谁

是否采用该项目，取决于现有宿主、目标文件格式和可接受的验证成本。以下信号可以用于作出明确判断。

适合谁

• 已经使用 Claude Code、Codex、OpenCode，或其他明确兼容 Agent Skills 规范的宿主。
• 主要资产是 Obsidian 仓库，并需要生成或编辑 .md、.base、.canvas 文件。
• 愿意使用开放文本格式，并能通过版本控制或文件差异审查智能体生成的内容。
• 需要把网页清理、结构化数据模板渲染与 Obsidian 笔记处理组合为本地工作流。
• 具备在测试仓库中验证批量变更的流程，不要求项目自身提供回滚服务。

不适合谁

• 需要一个独立运行、带图形界面和同步服务的 Obsidian 替代产品。
• 所用智能体不支持 Agent Skills 规范，也不能读取指定目录下的 SKILL.md。
• 必须获得明确的 SLA、性能基准、合规认证、审计报告或厂商支持承诺。
• 要求仓库直接提供 HTTP API、数据库、身份认证、容器镜像或集中式管理控制台。
• 无法允许宿主访问目标笔记目录，或无法在处理前移除不应交给智能体的敏感数据。

常见问题与排查（FAQ／Troubleshooting）

排查应优先检查安装层级、宿主兼容性和重启状态。README 没有提供统一错误码，因此需要根据所选宿主分别定位问题。

OpenCode 没有发现技能怎么办？

先确认完整仓库位于 ~/.opencode/skills/obsidian-skills/，并且技能文件结构为 skills/<skill-name>/SKILL.md。不要只把内部 skills/ 目录复制到错误层级，完成修正后重启 OpenCode。

README 明确说明无需修改 opencode.json 或其他配置文件。若目录和重启均已确认，官方仓库未提供进一步诊断命令，建议检查宿主自身输出并核对最新 README。

SSH 方式安装失败怎么办？

README 提供 HTTPS 地址作为替代，可执行 npx skills add https://github.com/kepano/obsidian-skills。这能避免依赖本机 GitHub SSH 凭据，但 npx 自身的网络和证书问题不属于本仓库已说明的范围。

Claude Code 应该复制哪个目录？

README 要求把仓库内容加入 Obsidian 仓库根目录下的 /.claude 文件夹，或 Claude Code 正在使用的其他目录。是否需要复制隐藏文件、如何刷新技能以及目录冲突处理方式未在资料中说明，应参考 Claude Agent Skills 文档。

Codex 的安装路径是否固定？

README 将 ~/.codex/skills 描述为典型路径，并要求复制仓库中的 skills/ 目录。实际路径若被宿主配置覆盖，应以 Codex 当前环境和 Agent Skills 规范为准。

是否需要配置 API Key？

给定资料没有列出 API Key、环境变量或认证字段。宿主智能体自身是否需要凭据不属于本仓库已提供的信息，不应为本项目虚构变量名或配置值。

生成的文件无法被 Obsidian 打开怎么办？

先确认扩展名与技能匹配：Markdown 使用 .md，Bases 使用 .base，JSON Canvas 使用 .canvas。随后对照相应官方格式文档检查内容；仓库资料没有提供内置校验器命令或自动修复流程。

可以在生产仓库直接批量执行吗？

README 没有提供事务、备份或回滚保证。根据本文作者的经验判断，应先在隔离副本或测试分支上运行，并在合并前审查文件差异，尤其是 Knap 批量生成和 CLI 写入任务。

项目地址与资源

以下链接均来自项目资料，可用于核对仓库内容、技能规范和对应开放格式。版本、安装行为与目录要求发生变化时，应以这些官方资源的最新内容为准。

• obsidian-skills GitHub 仓库
• Agent Skills 规范
• Claude Agent Skills 官方文档
• Obsidian Flavored Markdown 文档
• Obsidian Bases 语法文档
• Obsidian CLI 文档
• JSON Canvas 官方站点
• Defuddle GitHub 仓库
• Knap GitHub 仓库