notes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/notes — Internal Notes Librarian

/notes — 内部笔记管理员

Agentic note-filing skill for a Docmost wiki. Tag

/notes

(or

@notes

) during a chat. A subagent extracts durable knowledge by category, picks the best existing destination from your workspace structure, and falls back to an inbox when confidence is low.

This skill does not restructure your workspace. It learns from what's already there and files into existing pages.

用于Docmost wiki的智能笔记归档技能。在聊天中标记

/notes

（或

@notes

）。子代理会按类别提取持久化知识，从你的工作区结构中选择最佳的现有目标位置，当置信度较低时会回退到收件箱。

此技能不会重构你的工作区。它会从现有结构中学习，并归档到已有的页面中。

First-time setup

首次设置

The skill authenticates with a Docmost API key (Bearer token), not a user account. Generate one in Docmost:

Open
```
Settings → Account → API keys
```
Click Create API Key, name it (e.g.
```
notes-skill
```
)
Copy the key — Docmost shows it once

Then run setup. From anywhere:

bash

"$(dirname "$(readlink -f "$(npx --no-install skills which notes 2>/dev/null || echo ~/.agents/skills/notes/SKILL.md)")")/scripts/setup.sh"

Or simpler — just invoke

/notes

(or

@notes

) in your agent and it will detect the missing config and offer to run setup for you.

Direct path (after

npx skills add

bash

~/.agents/skills/notes/scripts/setup.sh

It will:

Ask for your Docmost base URL (e.g.
```
https://docs.example.com
```
)
Ask for the API key, verify it works against
```
/api/spaces
```
, store at
```
~/.docmost/api-key
```
(chmod 600)
Save base URL + key path at
```
~/.docmost/config
```
Discover your spaces and prompt for the inbox parent
Optionally create the
```
AI Notes Agent
```
parent + 4 subpages
Write
```
references/config.local.md
```
(gitignored) with the resolved IDs

Symlink

agents/notes-librarian.md

into

~/.claude/agents/

and

~/.codex/agents/

config.local.md

is gitignored. Never commit it.

Rotate by revoking the key in Docmost and re-running

./scripts/setup.sh

该技能通过Docmost API key（Bearer令牌）进行身份验证，而非用户账户。在Docmost中生成API密钥：

打开
```
Settings → Account → API keys
```
点击Create API Key，为其命名（例如
```
notes-skill
```
）
复制密钥 — Docmost只会显示一次

然后运行设置。在任意位置执行：

bash

"$(dirname "$(readlink -f "$(npx --no-install skills which notes 2>/dev/null || echo ~/.agents/skills/notes/SKILL.md)")")/scripts/setup.sh"

或者更简单的方式 — 直接在你的代理中调用

/notes

（或

@notes

），它会检测到缺失的配置并主动提供运行设置的选项。

直接路径（执行

npx skills add

后）：

bash

~/.agents/skills/notes/scripts/setup.sh

设置过程会：

询问你的Docmost基础URL（例如
```
https://docs.example.com
```
）
询问API密钥，验证其是否能访问
```
/api/spaces
```
，并将密钥存储在
```
~/.docmost/api-key
```
（设置权限chmod 600）
将基础URL和密钥路径保存到
```
~/.docmost/config
```
发现你的空间并提示选择收件箱父页面
可选创建
```
AI Notes Agent
```
父页面及其4个子页面
将解析后的ID写入
```
references/config.local.md
```
（已被git忽略）

将

agents/notes-librarian.md

软链接到

~/.claude/agents/

和

~/.codex/agents/

config.local.md

已被git忽略，切勿提交。

如需轮换密钥，在Docmost中撤销旧密钥并重新运行

./scripts/setup.sh

即可。

Trigger phrases

触发短语

```
/notes save this
```
```
/notes file this under <project|client>
```

/notes extract decisions

/notes extract action items

/notes update notes from this discussion

```
@notes ...
```
(same thing)
"document this", "save this discussion", "log this conversation"

```
/notes save this
```
```
/notes file this under <project|client>
```

/notes extract decisions

/notes extract action items

/notes update notes from this discussion

```
@notes ...
```
（功能相同）
"document this"、"save this discussion"、"log this conversation"

What the skill does

技能工作流程

Preflight: check that
```
<skill-dir>/references/config.local.md
```
exists. If not, the skill is unconfigured — tell the user "Notes skill isn't configured yet. Run setup now? (the script will prompt for your Docmost URL and API key)" and, on confirmation, execute
```
<skill-dir>/scripts/setup.sh
```
via Bash. Do not attempt to spawn the librarian without config.
Capture the conversation slice the user is referring to.
Spawn the
```
notes-librarian
```
subagent (
```
agents/notes-librarian.md
```
) with a self-contained prompt.
Return the subagent's report.

The subagent reads

references/config.local.md

for IDs,

references/filing-rules.md

for the destination decision tree, and

references/extraction.md

for bucket rules.

预检：检查
```
<skill-dir>/references/config.local.md
```
是否存在。如果不存在，说明技能未配置 — 告知用户“笔记技能尚未配置。现在运行设置吗？（脚本会提示你输入Docmost URL和API密钥）”，在用户确认后，通过Bash执行
```
<skill-dir>/scripts/setup.sh
```
。未配置时请勿尝试启动管理员代理。
捕获用户所指的对话片段。
启动
```
notes-librarian
```
子代理（
```
agents/notes-librarian.md
```
）并传入独立提示词。
返回子代理的报告。

子代理会从

references/config.local.md

读取ID，从

references/filing-rules.md

读取目标决策树，从

references/extraction.md

读取分类规则。

Hard rules (enforced inside the subagent)

硬性规则（在子代理内强制执行）

Append-preferred. No deletes, no moves, no renames.
Never auto-create a client/project parent page. Unknown entities go to the Inbox as candidates.
Every saved page leads with the metadata header (Type/Date/Source/Tags/Summary/Canonical/Topic/Project/Updated).
Internal-documentation writing style: bullets, short sentences, commands and names as first-class content, no filler.
Secrets never saved verbatim. Credentials trigger a rotation warning.

优先追加内容。不删除、不移动、不重命名。
绝不自动创建客户/项目父页面。未知实体作为候选项进入收件箱。
每个已保存的页面都以元数据标题开头（类型/日期/来源/标签/摘要/规范链接/主题/项目/更新时间）。
采用内部文档写作风格：使用项目符号、短句，将命令和名称作为核心内容，无冗余文字。
绝不原样保存机密信息。若检测到凭证，会触发轮换警告。

Output

输出

The subagent returns a fixed report:

Saved:
- Location:
- Note type:
- Confidence:
- Review status:

Captured:
- ...

Action items:
- ...

Open questions:
- ...

Updated:
- <page links>

Warnings:
- ...

子代理会返回固定格式的报告：

已保存：
- 位置：
- 笔记类型：
- 置信度：
- 审核状态：

已捕获内容：
- ...

行动项：
- ...

未解决问题：
- ...

已更新页面：
- <页面链接>

警告：
- ...

Files

文件结构

notes/
├── SKILL.md                              # this file
├── agents/
│   └── notes-librarian.md                # subagent definition (symlinked by setup.sh)
├── references/
│   ├── config.md                         # public defaults + how to override
│   ├── config.local.example.md           # template; copy to config.local.md
│   ├── extraction.md                     # bucket definitions
│   └── filing-rules.md                   # destination decision tree
└── scripts/
    ├── setup.sh                          # interactive first-time setup
    └── notes.sh                          # Docmost API wrapper

notes/
├── SKILL.md                              # 本文档
├── agents/
│   └── notes-librarian.md                # 子代理定义（由setup.sh创建软链接）
├── references/
│   ├── config.md                         # 公共默认配置及覆盖方法
│   ├── config.local.example.md           # 模板；复制为config.local.md使用
│   ├── extraction.md                     # 分类定义
│   └── filing-rules.md                   # 目标决策树
└── scripts/
    ├── setup.sh                          # 交互式首次设置脚本
    └── notes.sh                          # Docmost API包装器

Updating workspace cache

更新工作区缓存

When new clients/projects are added to Docmost, re-run

./scripts/setup.sh --refresh

to update the cached lists in

config.local.md

当Docmost中添加了新的客户/项目时，重新运行

./scripts/setup.sh --refresh

以更新

config.local.md

中的缓存列表。