docs-search

docs-search documentation retrieval

Internal enterprise library documentation retrieval: a single general-purpose skill covers all indexed libraries, with dynamic discovery, rather than one skill per library.

When you need internal library facts,directly run the script embedded in this skill, and do not guess private APIs from training data.

Script:scripts/query.mjs(Node ≥ 24, zero dependencies).Always run commands in the user's repository root directory（.pe.jsonc location): write the script path as an absolute path pointing to this skill; do not cd into the skill directory before running. The service address is read-only from the repository root directory .pe.jsonc in docs_server_url(the trailing slash is removed by the script; non-sensitive configuration must be committed to git).

Flow

1. Check configuration (always the first step)

Before running any query, read the current repository root directory .pe.jsonc, and confirm it contains docs_server_url。

Configured: go directly to step 2. Write the command as node <脚本绝对路径> …。
Missing: guide the user to fill it in:
1. Use the question tool to ask the user for the service address (request it from the documentation service administrator, in the form http://docs.internal:8080); it is forbidden to fabricate or guess an address.
2. Write to the current repository root directory .pe.jsonc(if it already exists, supplement or update the field; non-sensitive configuration must be committed to git). Format:
```
{
  "docs_server_url": "http://docs.internal:8080"
}
```
On first integration, you may also, according to the "Host project proactive retrieval" section, guide the user to add internal library guidance in the entry instruction file (such as AGENTS.md).

2. Query

node <脚本绝对路径> libraries
node <脚本绝对路径> search --q "<关键词> [关键词2]" [--library <slug>] [--limit 1~50]
node <脚本绝对路径> get --library <slug> --path <path> [--section <章节>]
node <脚本绝对路径> toc --library <slug> --path <path>

libraries: the slugs and document counts of indexed libraries. In most scenarios you can skip it and directly do a cross-library search (results include the library field); run it first to verify only when you need to limit results to a single library and are unsure of the slug spelling.
search: cross-library full-text search, at most 20 results (--limit adjustable from 1 to 50), in descending order of relevance. Results include library/path/title/description/snippet/sections。
get: get the full text, or --section to get a single ## section slice. The section name must exactly match the full title (case-insensitive); preferably choose it from the search results or from toc in sections .
toc: get only metadata and the section list, without the body text. When a document is very large and you only want to confirm its structure, use it first, then retrieve by section get。

Parameters containing spaces (--q、--section) must be quoted.

3. Query phrasing (adjust in order when you cannot find results)

The server side uses multi-word AND semantics (all words must hit the same document to count as a hit; empty results automatically degrade to any-word hits); Chinese is matched bycontiguous substringmatching, and English identifiers are matched by whole word. Construct the query:

Identifiers as-is from the source code：rowKey、skipErrorHandler can be matched as a whole word;row_key will be split into row、key two words.
Search by file name: the entire document path is indexed (compositions/use-dnd.md → use-dnd); when the file name or directory is known, you can search directly (use-dnd、index 总览); file name hits are weighted higher than incidental mentions in the body text.
For Chinese, use 2~6 character entity words: "virtual scrolling", "pagination"; do not write a whole sentence; in "how to use pagination", "how" and "use" will be stripped as stop words, leaving "pagination".
Component name + scenario word combination："Table 分页" a combination of two or three words like this is most effective; too many words makes the AND conditions too strict.
On empty results, try in order: reduce to 1~2 core words and search again → switch to synonyms (虚拟列表 ↔ 虚拟滚动) → switch to the English identifier → libraries confirm the target library exists → toc browse that library's index.md structure for clues.
Once there's a hit, look at snippet to judge relevance (when only the filename matches, the snippet is a path with highlighting, e.g. guide/<mark>installation</mark>.md); if relevant, get；sections the field already lists all section names of that document, so fetching precisely by section saves tokens.

4. Result handling

stdout is the server-side JSON; read it directly and do not show the raw JSON to the user.
On a non-2xx HTTP status the script exits non-zero; handle it per the troubleshooting table below. If the script reports "config file not found: .pe.jsonc" or "missing required field: docs_server_url", it means step 1 was not done or the configuration is missing; go back to step 1, complete it, and rerun.

Host project proactive retrieval

Skills are triggered by their description, but the AI may not know which internal libraries the project uses: if the entry instructions don't state them, it may guess from training data or reinvent the wheel. The host project should state its internal libraries in its own entry instructions (AGENTS.md / CLAUDE.md, etc.) so the AI proactively retrieves before writing code.

On first integration, or when you find the host project lacks this guidance, provide the following template and have the user replace the examples and placeholders according to the actual project and add it in an appropriate place:

## 内部库

- 写代码前先用 docs-search 技能检索内部库用法，禁止凭训练数据猜测
- `@cat-kit/*`（slug：`cat-kit`）：常用的轻量工具函数，优先使用，避免重复造轮子
- {其它内部库，一条一行，写包名、slug 与一句话说明}

Only prompt to add internal library guidance; do not guide installation or configuration of other skills in this repository, to avoid coupling.
Keep the template short: one line per internal library, stating the library name and slug and pointing to docs-search; leave details such as query methods and commands inside this skill.

Troubleshooting

Error (script stderr)	Cause	Handling
`找不到配置文件：.pe.jsonc` / `配置文件 … 缺少必填字段：docs_server_url`	Step 1 was not done or `.pe.jsonc` is not configured	Go back to step 1 and configure it in `.pe.jsonc` configure in
`docs_server_url 须以 http:// 或 https:// 开头`	Incorrect address format	Verify the address with the user
`请求失败：fetch failed（ECONNREFUSED/ENOTFOUND…）`	Service unreachable or domain resolution failed	Verify the address and network, report to the user/administrator, do not blindly retry
`请求超时（10 秒）`	No response from the server	Stop retrying, report to the user/administrator
`HTTP 400 missing_query`	`--q` is empty	Add keywords
`HTTP 400 invalid_limit`	`--limit` is not in 1~50	Change to an integer in 1~50
`HTTP 404 library_not_found`	`--library` spelling error or the library has been removed	Run `libraries` to verify the slug; if it's not in the list, tell the user that library is not included
`HTTP 404 not_found`（get/toc）	`--path` spelling error or the document has been deleted	Use the `path` from the search results verbatim and retry; if it still can't be found, search again with keywords
`HTTP 404 section_not_found`	Section name does not match the heading	The message lists all available section names of that document, pick the correct name from them and retry once; do not give up
`HTTP 500 internal`	Server-side failure	Relay the original error text to the user/administrator

Anti-patterns

Copying/creating a retrieval skill for a single library
Putting docs_server_url into .env or hardcoding it in code (non-sensitive configuration must be written into .pe.jsonc and committed to the repository)
When missing docs_server_url do not ask the user, fabricate or guess the service address and keep running
cd into the skill directory to run the script, or treat the entire natural language sentence as --q
When nothing is found, endlessly swap words and spin idly: adjust according to the order in Section 3; if there is still no result, explain to the user and stop
Implement internal library calls based on training data without retrieval