markdownknowledge

将本地 Markdown 知识库与 OpenClaw 集成，支持语义检索和上下文注入。仅在用户触发时检索（搜索知识库、查一下知识库等），不主动注入。

Security Scan

The skill generally does what it says (local Markdown semantic search), but there are internal inconsistencies about automatic injection/refresh and it auto-downloads a binary during init and will read any Markdown (including files containing secrets) — review before installing.

Purpose & Capability

Name/description match the implemented functionality: the skill scans local Markdown, builds a JSON index, and exposes search/build/stats actions. Declared filesystem permissions (read Markdown, write index) are consistent with purpose. However, some documentation (PROJECT.md, README.md, clawhub.json) asserts features like automatic context injection and auto-refresh which conflict with the top-level SKILL.md claim of 'trigger-only' retrieval.

Instruction Scope

SKILL.md instructs trigger-only behavior, but other included docs repeatedly state 'automatic context injection' and 'real-time sync/auto_refresh'. The code itself exposes actions for search/build/stats (triggered use), but there is a config parameter auto_refresh (default true in some manifests) that could enable background/index refresh behavior. Also the skill will read arbitrary files from the configured knowledge_path and may include their content in search results/formatting — that means any sensitive data present in Markdown could be revealed to the agent when triggered.

Install Mechanism

There is no registry install spec in the package, but scripts/knowledge_base.py's init will attempt to auto-download ripgrep from GitHub releases (https://github.com/BurntSushi/ripgrep/releases/...) and extract it to ~/.local/bin. Downloading and extracting an executable is a higher-risk install step than pure instruction-only; the download host (GitHub releases) is well-known, but the script writes binaries to the user's home area and uses /tmp for temporary files. The skill otherwise does not pull other remote code during runtime.

Credentials

The skill requests no environment variables or external credentials, which matches its described local purpose. However, it will read all Markdown under the configured knowledge_path and write an index file. The included sample index.json demonstrates real user data (including API keys and private values inside Markdown). Because the skill returns document snippets and formatted results to the agent, any secrets embedded in Markdown can be surfaced to the agent and (depending on agent behavior) transmitted beyond the machine. The number of environment/credential requests is low, but the data-access scope (entire Markdown folder) is broad and should be constrained by the user.

Persistence & Privilege

always: false and user-invocable: true. The skill does not request permanent platform-wide inclusion nor does it modify other skills' configurations. It writes its own config/index under its skill directory and can install ripgrep to ~/.local/bin during init, which is limited to the user's account and not a system-wide privilege escalation.

What to consider before installing

What to check before installing/using this skill: - Understand data access: the skill will read every .md under the configured knowledge_path and write an index file. Remove or relocate any Markdown that contains secrets (API keys, private tokens, passwords) or sensitive personal data before building the index. - Decide about auto-refresh: some manifests default auto_refresh=true while SKILL.md claims trigger-only retrieval. If you want no background updates or automatic injection, set auto_refresh to false and verify the agent only invokes search when you request it. - Inspect and control init behavior: running the provided init will attempt to download ripgrep from GitHub and install it to ~/.local/bin. If you prefer not to allow automatic downloads, install ripgrep yourself or edit the script to skip ensure_ripgrep. - Review index contents: after building, open the index.json to confirm it does not contain unintended secrets before invoking the skill in a shared/online agent session. - Limit scope: set knowledge_path to a narrow directory containing only documents you are comfortable exposing to the agent; use exclude_patterns to skip folders with sensitive content. - Run in a safe environment first: consider running build/search locally in an isolated account/container to observe behavior, then integrate into your primary agent once satisfied. Confidence note: medium — most items are straightforwardly supported by the code, but some contradictory documentation entries (automatic injection vs trigger-only) and the auto-download behavior increase uncertainty; examining runtime config and running a manual build will resolve the remaining questions.

Markdown Knowledge Base

将您的本地 Markdown 知识库与 OpenClaw 集成，让 AI 助手能够基于您的专业知识回答问题。

核心原则

触发式检索 - 仅在用户明确要求时检索知识库，不主动注入。

使用流程

1. 收到用户触发词 → 检索知识库

当用户说以下内容时，调用 search 动作：

• "搜索知识库"
• "查一下知识库"
• "知识库里..."

2. 搜到结果 → 注入上下文并回答

# 调用示例
results = action_search("用户问题关键词")

3. 搜不到结果 → 明确告知

告诉用户"知识库中没有找到相关信息"，然后基于通用知识回答。

命令

命令	说明
python3 knowledge_base.py build	构建/更新索引
python3 knowledge_base.py search <词>	搜索知识库
python3 knowledge_base.py stats	查看统计
python3 knowledge_base.py init	初始化配置

安装

clawhub install markdown-knowledge
python3 ~/.openclaw/workspace/skills/markdown-knowledge/scripts/knowledge_base.py init
python3 ~/.openclaw/workspace/skills/markdown-knowledge/scripts/knowledge_base.py build

配置

编辑 ~/.openclaw/workspace/skills/markdown-knowledge/config.json：

{
    "knowledge_path": "~/Knowledge",
    "index_path": "~/.openclaw/workspace/skills/markdown-knowledge/index.json",
    "search_top_k": 3,
    "auto_refresh": false
}

隐私说明

• ✅ 触发式检索 - 仅用户明确要求时检索
• ❌ 无全局注入 - 不会主动注入知识库内容
• ❌ 无后台监听 - 不在后台自动运行

文件结构

markdown-knowledge/
├── SKILL.md
├── clawhub.json            # clawhub 元数据
├── scripts/
│   └── knowledge_base.py   # CLI 入口
├── src/
│   ├── __init__.py
│   ├── config.py           # 配置加载
│   ├── actions.py          # OpenClaw 动作
│   └── knowledge_core.py   # 核心检索逻辑
├── references/
│   └── README.md          # 详细文档
└── assets/