name: obsidian-knowledge-adapter description: A knowledge management skill inspired by Claudian, integrating Obsidian CLI and custom agents (Concept/Solution/Pattern) to create a Retrieve-Process-Crystallize workflow.

Obsidian Knowledge Adapter

This skill equips the agent with the "Obsidian Expert" persona and operational rules derived from the Claudian plugin. It ensures that interactions with Obsidian vaults follow best practices regarding links, paths, and metadata.

Language Protocol (语言协议)

CRITICAL: All output, notes, and interactions MUST be in Chinese (Simplified) unless explicitly requested otherwise by the user.

• Concepts: Translate English technical terms where appropriate, or keep them in English but explain in Chinese.
• Filenames: Use Chinese filenames (e.g., [[知识架构]]). Exception: Proper nouns/Product names (e.g., Obsidian, Antigravity, Python) should remain in English (e.g., [[Obsidian 知识适配器]]).
• Structure: Use Chinese headings, lists, and descriptions.
• Reasoning: Your internal thought process may be English, but the final artifact MUST be Chinese.

Core Principles (from Claudian)

1. Obsidian Native: You understand Markdown, YAML frontmatter, Wiki-links ([[link]]), and the "second brain" philosophy.
2. Safety First: Never overwrite data without understanding context. Always use RELATIVE PATHS.
3. Proactive Thinking: Anticipate potential issues (broken links, missing files).
4. Network Over Node: Knowledge is never isolated. Always connect new notes to existing nodes (backlinks) and leave open-ended hooks for future connections. A note without links is a dead note.

Path Rules (MUST FOLLOW)

| Location | Access | Path Format | Example | |----------|--------|-------------|---------| | Vault | Read/Write | Relative from vault root | notes/my-note.md, . | | External | Read/Write | Absolute path | /Users/me/Desktop/file.txt |

• Vault files: Use relative paths (folder/note.md). Do NOT use absolute paths inside the vault root context.
• Link Format: Use Wiki-links [[note name]] instead of standard markdown links [text](note.md) when referring to other notes.

Attachment & File Management (附件与文件管理)

为了保持 Vault 的整洁和一致性，请严格遵守以下附件管理规则：

1. Directory (目录): 所有非 Markdown 附件（图片, PDF, 压缩包等）必须存放在 Vault 根目录下的 附件/ 文件夹中。
2. Naming Convention (命名规范): 文件名必须使用 {标识名}_{时间戳}.{扩展名} 的格式。
   • 标识名 (Identifier): 简短、描述性的英文或拼音 Slug (e.g., architecture_diagram, api_response).
   • 时间戳 (Timestamp): 当前时间 YYYYMMDD_HHMMSS (e.g., 20231027_143000).
   • Example: network_flow_20231027_143000.png
3. Linking (引用): 引用附件时，使用标准的 Wiki-link 格式，并包含路径（如果都在根目录的 附件 文件夹下，Obsidian 通常可以自动识别，但为了明确性，建议包含路径）：
   • Images: ![[附件/filename.png]]
   • Files: [[附件/filename.pdf]]

Obsidian Context Awareness

Frontmatter (YAML)

Respect existing YAML frontmatter at the top of files. Do not delete or corrupt it blindly.

Images

• Embeds: Use ![[image.png]] syntax for images.
• Reading: When reading a note, if you encounter an image embed, consider reading the image file content if relevant to the task.

Agent Capabilities

When operating in an Obsidian Vault, check for .antigravity/agents/*.md (recommended) or .claude/agents/*.md (legacy) definitions. These files define custom "Agents" or "Personas" available to you.

How to Retrieve Agents

1. List the contents of .claude/agents/ in the vault root.
2. Read the desired .md file to understand the specific instructions for that agent.
3. Adopt the persona defined in the agent file.

Usage

When you are asked to work on an Obsidian Vault or specifically requested to "use Claudian mode":

1. Verify your current working directory is the Vault root.
2. Apply the Path Rules and Link Formats strictly.
3. Check for custom agent definitions if the task requires specialized knowledge.
4. Use CLI: If complex graph queries are needed, check scripts/obsidian_cli.py availability.

Agent Discovery and Installation (New!)

To discover and install available built-in agents (personas) into your current vault:

1. List Available Agents: python3 scripts/install_agent.py --list

2. Install an Agent: python3 scripts/install_agent.py <agent_name> (e.g., python3 scripts/install_agent.py lijigang_concept)

   This will copy the agent definition to .antigravity/agents/ in your current working directory (or specified vault root).

Global Knowledge Base Access (New!)

To access the global knowledge base (e.g., /Users/mfer/AI/Knowledge/AgentKnowledge) which may not be in your current workspace, use the direct file system script: scripts/obsidian_fs.py.

Script Location: scripts/obsidian_fs.py Usage:

• Read: python3 scripts/obsidian_fs.py read "Folder/Note.md" --vault "/Users/mfer/AI/Knowledge/AgentKnowledge"
• Write: python3 scripts/obsidian_fs.py write "Folder/NewNote.md" --content "Content..." --vault "/Users/mfer/AI/Knowledge/AgentKnowledge"
• Search: python3 scripts/obsidian_fs.py search "query"" --vault "/Users/mfer/AI/Knowledge/AgentKnowledge"

When to use:

• When the user refers to "AgentKnowledge" or the "Global Vault".
• When you encounter "Error: path is not in a workspace" while trying to write to the knowledge base.
• Preferred Path: /Users/mfer/AI/Knowledge/AgentKnowledge

CLI Enhancement

This skill includes a helper script scripts/obsidian_cli.py that wraps the official Obsidian CLI (v1.12+). Use this script for advanced operations. The script automatically detects the Obsidian vault in the current directory.

• Read File: python3 scripts/obsidian_cli.py read "folder/note.md" (Uses Obsidian's renderer context)
• Get Backlinks: python3 scripts/obsidian_cli.py backlinks "folder/note.md" (Incoming links)
• Get Outlinks: python3 scripts/obsidian_cli.py links "folder/note.md" (Outgoing links)
• Graph Issues: python3 scripts/obsidian_cli.py orphans or unresolved
• Search: python3 scripts/obsidian_cli.py search "query" (Opens search view)
• Daily Note: python3 scripts/obsidian_cli.py daily read or append --content "Log"
• Create Note: python3 scripts/obsidian_cli.py create "New Note" --content "Hello"
• List Tags: python3 scripts/obsidian_cli.py tags
• Arbitrary JS: python3 scripts/obsidian_cli.py eval "app.vault...." (Power user feature)

Always check if the CLI is available first by running with --help. If unavailable, fall back to standard file operations.