## 项目概述

obsidian-skills 是一个为 Obsidian 设计的 Agent Skills 集合，遵循 Agent Skills 规范，使兼容的 AI 代理（如 Claude Code、Codex、OpenCode）能够通过命令行或直接操作文件来创建和编辑 Obsidian 的开放格式文件，包括 Markdown、Bases 和 JSON Canvas。该项目由 kepano 开发，采用 MIT 许可证。

## 核心功能

- **obsidian-markdown**：创建和编辑 Obsidian Flavored Markdown（.md）文件，支持 wikilinks、embeds、callouts、properties 等 Obsidian 特有语法。
- **obsidian-bases**：创建和编辑 Obsidian Bases（.base）文件，支持视图、过滤器、公式和摘要。
- **json-canvas**：创建和编辑 JSON Canvas（.canvas）文件，支持节点、边、分组和连接。
- **obsidian-cli**：通过 Obsidian CLI 与 Obsidian vault 交互，包括插件和主题开发。
- **defuddle**：使用 Defuddle 从网页提取干净的 Markdown，去除杂乱内容以节省 token。

## 适用与不适用场景

**适用场景**：
- 使用 AI 代理自动化管理 Obsidian 笔记库。
- 需要以编程方式创建或编辑 Obsidian 格式文件。
- 开发 Obsidian 插件或主题时，通过 CLI 进行交互。
- 从网页提取内容并转换为 Markdown 以节省 token。

**不适用场景**：
- 非 Obsidian 用户或不需要 Obsidian 特定格式的场景。
- 需要图形界面操作而非命令行或代理操作的场景。
- 对非 Agent Skills 兼容的 AI 工具（如某些专有助手）可能不适用。

## 技术架构与依赖

- **Agent Skills 规范**：遵循 [agentskills.io/specification](https://agentskills.io/specification)，确保与多种代理兼容。
- **Obsidian CLI**：用于与 Obsidian vault 交互。
- **Defuddle**：用于网页内容提取。
- **依赖**：需要安装 Obsidian 或相关 CLI 工具；具体依赖未在仓库中详细说明。

## 安装与快速开始

### 通过 Marketplace 安装

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

### 通过 npx skills 安装

```
npx skills add git@github.com:kepano/obsidian-skills.git
```

或使用 HTTPS：

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

### 手动安装

#### Claude Code

将仓库内容添加到 Obsidian vault 根目录下的 `/.claude` 文件夹中。

#### Codex

将 `skills/` 目录复制到 Codex skills 路径（通常为 `~/.codex/skills`）。

#### OpenCode

克隆整个仓库到 OpenCode skills 目录：

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

确保目录结构为 `~/.opencode/skills/obsidian-skills/skills/<skill-name>/SKILL.md`。OpenCode 会自动发现所有 `SKILL.md` 文件，无需额外配置，重启后生效。

## 典型使用方法

安装后，AI 代理可以调用各个 skill 来执行任务。例如：

- 使用 `obsidian-markdown` 创建带有 wikilinks 和 callouts 的笔记。
- 使用 `obsidian-bases` 创建数据库视图。
- 使用 `json-canvas` 创建思维导图或流程图。
- 使用 `obsidian-cli` 管理 vault 或开发插件。
- 使用 `defuddle` 将网页内容转换为干净的 Markdown。

具体命令和参数请参考各 skill 的 `SKILL.md` 文件。

## 配置与部署要点

- 对于 Claude Code，需要将仓库内容放置在正确的 `/.claude` 目录。
- 对于 Codex，需要将 `skills/` 目录复制到正确的路径。
- 对于 OpenCode，必须克隆整个仓库，而不是仅复制内部 `skills/` 文件夹。
- 确保代理工具支持 Agent Skills 规范。
- 可能需要配置 Obsidian CLI 的环境变量或路径。

## 限制、风险与许可证

- **限制**：仓库资料未提供详细的限制说明；可能依赖 Obsidian 的特定版本或 CLI 工具。
- **风险**：使用第三方技能可能带来安全风险，建议审查技能内容；仓库内容可能包含未经验证的代码。
- **许可证**：MIT License。

## 官方链接

- GitHub 仓库：[https://github.com/kepano/obsidian-skills](https://github.com/kepano/obsidian-skills)
- Agent Skills 规范：[https://agentskills.io/specification](https://agentskills.io/specification)
- Obsidian Flavored Markdown：[https://help.obsidian.md/obsidian-flavored-markdown](https://help.obsidian.md/obsidian-flavored-markdown)
- Obsidian Bases：[https://help.obsidian.md/bases/syntax](https://help.obsidian.md/bases/syntax)
- JSON Canvas：[https://jsoncanvas.org/](https://jsoncanvas.org/)
- Obsidian CLI：[https://help.obsidian.md/cli](https://help.obsidian.md/cli)
- Defuddle：[https://github.com/kepano/defuddle](https://github.com/kepano/defuddle)

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README（https://github.com/kepano/obsidian-skills）
- 分析时间：2025年4月（基于当前日期）