local-ref

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Local Reference

本地参考

Cache library documentation locally so every session reads from disk instead of re-fetching from external sources. Local docs load via

Read

tool (free, instant) instead of API calls (tokens + latency).

将库文档本地缓存，这样每次会话都从磁盘读取，而非重新从外部源获取。本地文档通过

Read

工具加载（免费、即时），无需调用API（消耗令牌且有延迟）。

Sources

来源

Fetch documentation from any of these, in order of preference:

Context7 API — curated library docs with code examples. See
```
references/context7-api.md
```
.
WebFetch — official documentation sites (e.g., developer.wordpress.org, getbootstrap.com)
Manual — user-provided docs, internal wikis, or CLI
```
--help
```
output

可从以下任一来源获取文档，优先级如下：

Context7 API —— 带有代码示例的精选库文档。详见
```
references/context7-api.md
```
。
WebFetch —— 官方文档站点（例如developer.wordpress.org、getbootstrap.com）
Manual —— 用户提供的文档、内部维基或CLI
```
--help
```
输出

Commands

命令

Init —

local-ref init

初始化 —

local-ref init

Set up local documentation cache for a project.

Detect project technologies from these sources:
- ```
package.json
```
  (JS/Node dependencies)
- ```
composer.json
```
  (PHP dependencies)
- ```
AGENTS.md
```
  /
```
CLAUDE.md
```
  (mentioned frameworks)
- ```
requirements.txt
```
  /
```
pyproject.toml
```
  (Python)
- ```
Gemfile
```
  (Ruby)
- ```
go.mod
```
  (Go)
Confirm with user which technologies to cache. Suggest the top 3-5 most relevant. Skip generic/obvious ones (e.g., don't cache "JavaScript" docs for a JS project).
For each technology: a. Scan project code to identify which APIs/patterns are actually used b. Fetch documentation from best available source (see Sources above) c. Filter fetched content to patterns relevant to this project
Write project-specific docs to
```
docs/reference/<topic>.md
```
:
- Start each file with the standard header (see File Header Format below)
- Include only patterns relevant to this project's actual code
- Cross-reference actual project files when possible (e.g., "Used in
```
lib/acf.php
```
  ")
- Target 100-200 lines per file — enough to be useful, small enough to read quickly

Update AGENTS.md — add a

## Local Reference Documentation

section with verbal references (NOT

-references) to the docs:

markdown

## Local Reference Documentation

The `docs/reference/` directory contains project-specific API references.
Check these files before using external documentation tools:

- `docs/reference/<file>.md` — <brief description>

为项目设置本地文档缓存。

从以下来源检测项目技术栈：
- ```
package.json
```
  （JS/Node依赖）
- ```
composer.json
```
  （PHP依赖）
- ```
AGENTS.md
```
  /
```
CLAUDE.md
```
  （提及的框架）
- ```
requirements.txt
```
  /
```
pyproject.toml
```
  （Python）
- ```
Gemfile
```
  （Ruby）
- ```
go.mod
```
  （Go）
与用户确认要缓存的技术栈。建议选择最相关的3-5项。跳过通用/显而易见的内容（例如，JS项目无需缓存“JavaScript”文档）。
针对每项技术栈： a. 扫描项目代码，识别实际使用的API/模式 b. 从最佳可用来源获取文档（见上方“来源”部分） c. 过滤获取的内容，仅保留与本项目相关的模式
将项目专属文档写入
docs/reference/<topic>.md
：
- 每个文件以标准页眉开头（见下方“文件页眉格式”）
- 仅包含与本项目实际代码相关的模式
- 尽可能关联实际项目文件（例如：“在
```
lib/acf.php
```
  中使用”）
- 每个文件目标长度为100-200行——足够实用，且便于快速阅读

更新AGENTS.md —— 添加

## Local Reference Documentation

部分，使用文字描述引用文档（不要使用

引用）：

markdown

## Local Reference Documentation

The `docs/reference/` directory contains project-specific API references.
Check these files before using external documentation tools:

- `docs/reference/<file>.md` — <brief description>

Update —

local-ref update

更新 —

local-ref update

Refresh existing local docs.

Read
```
docs/reference/
```
to find existing doc files
For each file, parse the
```

```
header to determine source type and parameters (
```
libraryId
```
/
```
query
```
for context7,
```
url
```
for webfetch)
Re-fetch based on source type:
- ```
context7
```
  — re-fetch using
```
libraryId
```
  and
```
query
```
- ```
webfetch
```
  — re-fetch from
```
url
```
- ```
manual
```
  — skip (flag for user review if stale)
Merge new content while preserving project-specific annotations and cross-references
Update the
```

```
date
Report what changed (updated, skipped manual, failed)

刷新现有本地文档。

读取
```
docs/reference/
```
目录，找到现有文档文件
针对每个文件，解析
```

```
页眉以确定源类型和参数（Context7的
```
libraryId
```
/
```
query
```
，WebFetch的
```
url
```
）
根据源类型重新获取内容：
- ```
context7
```
  —— 使用
```
libraryId
```
  和
```
query
```
  重新获取
- ```
webfetch
```
  —— 从
```
url
```
  重新获取
- ```
manual
```
  —— 跳过（若内容过时则标记供用户审核）
合并新内容，同时保留项目专属注释和关联引用
更新
```

```
日期
报告变更内容（已更新、跳过手动文档、获取失败）

Lookup —

local-ref lookup <topic>

查找 —

local-ref lookup <topic>

Find documentation, local-first.

Check
```
docs/reference/
```
for a matching file (grep for topic keywords)
If found, read the local file and quote/apply the relevant sections to the current task
If not found, fetch from external source, then ask user if the result should be saved locally

查找文档，优先使用本地缓存。

在
```
docs/reference/
```
目录中查找匹配文件（通过关键词 grep 搜索）
若找到，读取本地文件并引用/应用与当前任务相关的章节
若未找到，从外部源获取，然后询问用户是否要将结果保存到本地

Save —

local-ref save

(opportunistic, mid-project)

保存 —

local-ref save

（项目进行中按需使用）

When working on a project and you fetch documentation from an external source (Context7, WebFetch, etc.) that would be useful across sessions:

After using the fetched docs to complete the current task, offer: "This documentation could be useful in future sessions. Save to
```
docs/reference/
```
?"
If user agrees, write a project-specific version (not raw dump) to
```
docs/reference/<topic>.md
```
with the standard header (see File Header Format)
Add the new file to the AGENTS.md
```
## Local Reference Documentation
```
bullet list so future sessions discover it
Continue with the original task

This keeps docs growing organically as the project evolves, without requiring explicit

init

update

runs.

在项目开发过程中，当你从外部源（Context7、WebFetch等）获取了对后续会话有用的文档时：

使用获取的文档完成当前任务后，询问用户：“此文档对后续会话可能有用，是否保存到
```
docs/reference/
```
？”
若用户同意，将项目专属版本（非原始转储）写入
```
docs/reference/<topic>.md
```
，并添加标准页眉（见“文件页眉格式”）
将新文件添加到AGENTS.md的
```
## Local Reference Documentation
```
项目符号列表中，以便后续会话能够发现
继续执行原任务

这样可随着项目演进自然扩充文档，无需显式运行

init

或

update

命令。

Passive Behavior (via AGENTS.md)

被动行为（通过AGENTS.md）

The

init

command adds a

## Local Reference Documentation

section to AGENTS.md. This section loads every session (~80 tokens) and tells Claude to check

docs/reference/

before external lookups. This passive guidance works without loading the skill itself.

init

命令会在AGENTS.md中添加

## Local Reference Documentation

部分。该部分会在每次会话加载（约80令牌），告知Claude在进行外部查找前先检查

docs/reference/

目录。此被动引导无需加载技能本身即可生效。

File Header Format

文件页眉格式

Every cached doc file MUST start with this machine-readable header. The

update

command depends on it.

markdown

undefined

每个缓存文档文件必须以以下机器可读页眉开头。

update

命令依赖此页眉。

markdown

undefined

Vite Asset Pipeline — Project Reference

Content here...


Header fields:

| Field | Required | Values |
|-------|----------|--------|
| `source` | yes | `context7`, `webfetch`, `manual` |
| `libraryId` | if context7 | Context7 library ID |
| `url` | if webfetch | Source URL |
| `query` | if applicable | Query used to fetch content |
| `cached` | yes | ISO date (`YYYY-MM-DD`) of last fetch |

For manually created docs, use `source="manual"`:

```markdown

Content here...


页眉字段：

| 字段 | 是否必填 | 取值 |
|-------|----------|--------|
| `source` | 是 | `context7`, `webfetch`, `manual` |
| `libraryId` | 当source为context7时必填 | Context7库ID |
| `url` | 当source为webfetch时必填 | 源URL |
| `query` | 适用时必填 | 获取内容时使用的查询词 |
| `cached` | 是 | 最后获取日期（ISO格式 `YYYY-MM-DD`） |

对于手动创建的文档，使用`source="manual"`：

```markdown

Internal Auth API — Project Reference

undefined

undefined

When NOT to Cache

无需缓存的场景

Skip local caching when:

Rapidly evolving APIs — bleeding-edge or pre-1.0 libraries where docs change weekly
One-off lookups — if you only need one fact, fetching is cheaper than maintaining a file
Already in AGENTS.md — if the project's agent instructions already cover the topic

When in doubt, cache. Stale docs are better than no docs —

update

can refresh context7 and webfetch sources automatically (manual sources are flagged for review).

以下情况跳过本地缓存：

快速演进的API —— 前沿或1.0版本前的库，其文档每周更新
一次性查找 —— 若仅需单个信息点，获取文档比维护文件更划算
已包含在AGENTS.md中 —— 若项目的Agent指令已涵盖该主题

若有疑问，优先缓存。过时文档总比没有好——

update

命令可自动刷新Context7和WebFetch来源的内容（手动来源会标记供审核）。

Key Design Rules

核心设计规则

Verbal references only — never add
```
@docs/reference/...
```
to AGENTS.md (would bloat system prompt). Use plain text descriptions so Claude reads files on-demand.
Project-specific over generic — don't dump raw API output. Tailor examples to the project's actual code, file structure, and patterns.
Cross-reference project files — mention where patterns are used (e.g., "see
```
lib/assets.php
```
for implementation").
One file per topic — keep docs modular. Don't create one giant reference file.
100-200 lines per file — see target in
```
init
```
command above.

仅使用文字描述引用 —— 切勿在AGENTS.md中添加
```
@docs/reference/...
```
（会膨胀系统提示词）。使用纯文本描述，让Claude按需读取文件。
优先项目专属内容，而非通用内容 —— 不要直接转储原始API输出。根据项目的实际代码、文件结构和模式调整示例。
关联项目文件 —— 提及模式的使用位置（例如：“详见
```
lib/assets.php
```
中的实现”）。
每个主题一个文件 —— 保持文档模块化。不要创建单一的巨型参考文件。
每个文件100-200行 —— 见
```
init
```
命令中的目标要求。

File Naming Convention

文件命名规范

Use descriptive kebab-case names:

docs/reference/
├── acf-patterns.md
├── vite-asset-pipeline.md
├── wordpress-cpt-taxonomy.md
├── bootstrap-grid-components.md
└── react-hooks-patterns.md

使用描述性的短横线分隔命名（kebab-case）：

docs/reference/
├── acf-patterns.md
├── vite-asset-pipeline.md
├── wordpress-cpt-taxonomy.md
├── bootstrap-grid-components.md
└── react-hooks-patterns.md

External Source References

外部来源参考

See

references/context7-api.md

for Context7 API endpoints and common library IDs.

Context7 API端点和常用库ID详见

references/context7-api.md

。

local-ref

Original

Translation

Local Reference

本地参考

Sources

来源

Commands

命令

Init —
`local-ref init`

初始化 —
`local-ref init`

Update —
`local-ref update`

更新 —
`local-ref update`

Lookup —
`local-ref lookup <topic>`

查找 —
`local-ref lookup <topic>`

Save —
`local-ref save`
(opportunistic, mid-project)

保存 —
`local-ref save`
（项目进行中按需使用）

Passive Behavior (via AGENTS.md)

被动行为（通过AGENTS.md）

File Header Format

文件页眉格式

Vite Asset Pipeline — Project Reference

Vite Asset Pipeline — Project Reference

Internal Auth API — Project Reference

Internal Auth API — Project Reference

When NOT to Cache

无需缓存的场景

Key Design Rules

核心设计规则

File Naming Convention

文件命名规范

External Source References

外部来源参考

local-ref

Original

Translation

Local Reference

本地参考

Sources

来源

Commands

命令

Init — local-ref init

初始化 — local-ref init

Update — local-ref update

更新 — local-ref update

Lookup — local-ref lookup <topic>

查找 — local-ref lookup <topic>

Save — local-ref save (opportunistic, mid-project)

保存 — local-ref save（项目进行中按需使用）

Passive Behavior (via AGENTS.md)

被动行为（通过AGENTS.md）

File Header Format

文件页眉格式

Vite Asset Pipeline — Project Reference

Vite Asset Pipeline — Project Reference

Internal Auth API — Project Reference

Internal Auth API — Project Reference

When NOT to Cache

无需缓存的场景

Key Design Rules

核心设计规则

File Naming Convention

文件命名规范

External Source References

外部来源参考

Init —
`local-ref init`

初始化 —
`local-ref init`

Update —
`local-ref update`

更新 —
`local-ref update`

Lookup —
`local-ref lookup <topic>`

查找 —
`local-ref lookup <topic>`

Save —
`local-ref save`
(opportunistic, mid-project)

保存 —
`local-ref save`
（项目进行中按需使用）