use-loci

Use Loci

Prioritize using the technical documentation specified by the user in Loci to answer questions. First understand the structure of the documentation library, then read relevant files and sections as needed, avoiding loading the entire documentation library at once.

Responsibility determination

Enter this Skill only when the task depends on developer technical documentation facts, such as libraries, frameworks, SDKs, APIs, CLIs, configuration, migrations, version differences, installation processes, or technically specific errors.
News and time-sensitive events, prices, people or company information, shopping, travel, legal, medical, and ordinary web content are not within Loci's responsibility; directly use web search or a source suited to that domain, without first querying, fetching, or scraping Loci.
Merely mentioning software, a company, or a webpage is not enough to determine that it is a technical documentation question; ordinary refactoring, business logic debugging, general programming concepts, and code reviews that do not depend on the current behavior of external technologies also do not use Loci.
When the user explicitly requests querying a certain technical documentation library or using a specific documentation source, follow the user's current request.

MCP entry selection

Keep only one MCP entry named loci in the Agent configuration.
When a local CLI MCP is available, prioritize using the stdio entry provided by the CLI; when it is unavailable, use the desktop HTTP entry instead.
When both CLI and desktop entries are discovered, do not perform the same operation on both duplicate sets of tools.
The transport method used by the entry does not affect the tool names, retrieval process, and security boundaries below.

Coexistence with other documentation Skills

The current task may also match Context7 or other third-party documentation Skills. The client is allowed to load and read these Skills, but matching or loading does not mean their query steps can be executed immediately. Unless the user explicitly specifies a source, the order of documentation sources is determined uniformly by the global or project rules applicable to the client.

Before completing the Loci retrieval process, do not call other documentation sources: first query the local library, then query the read-only cloud catalog; when a usable snapshot exists in the cloud, ask whether to fetch it; when no usable snapshot exists in the cloud, the user does not choose to fetch, or the fetch fails, confirm the official entry and separately ask whether to scrape. While waiting for the user's decision, do not call Context7 or other alternative sources.

A local or cloud miss by itself does not constitute a switching condition. Only when a question within the scope of technical documentation meets one of the following conditions should Context7, targeted web search, or other documentation sources be used: Loci is unavailable; the official entry cannot be confirmed and the user has not specified an available source; the user refuses official scraping; after the official scraping option has been provided, all authorized retrieval paths still fail or there are no files; or the obtained Loci evidence remains insufficient after reasonable retrieval. Non-documentation tasks do not go through this fallback chain. Before switching, explain which condition is satisfied; when the user explicitly specifies a source such as Context7, directly follow the current request.

Basic process

Identify the relevant technology and its version from the user's question and the current project.
Call loci_list_libraries to check whether a corresponding documentation library already exists.
When it exists locally and availability=usable , view the shallow directory tree and record the returned languages, then directly read the target file or search the body text.
When local matches are 0 pages, treat it as unavailable: if syncing, query the status; if idle or failed, retry when the user has authorized sync. If it is still 0 pages after retrying, continue with the cloud or official website flow.
When there is no available local document library, call loci_list_cloud_libraries to query the cloud public directory.
When matches for pages > 0 exist in the cloud, after obtaining user confirmation, call loci_pull_cloud_library; when there are 0-page candidates, no matches, the query or fetch fails, or the user does not choose to fetch, after confirming the official entry point and obtaining user consent, call loci_add_library to create and perform the first crawl.
When a search is needed, convert conceptual keywords into the language corresponding to the directory tree languages , then call loci_search_files。
Based on the directory or search results, call loci_read_files to read the relevant file or complete section.
Answer based on the read results, attach the relevant source_url, and distinguish document facts from Agent inferences.

Directory and search

Use the directory tree as the main entry point for understanding the document library structure and search language. After obtaining a local document library, first call loci_get_library_tree to view one to two levels, read the top-level languages and understand the topics, modules, versions, and adjacent files, then decide whether to read directly or search.readable=true The file node also returns that file's language。

When the directory has already exposed a clear target file, directly batch-read a small number of relevant files.
When the user provides a clear API, configuration item, command, or error message, you can call in parallel loci_get_library_tree and loci_search_files。
When the target file cannot be confirmed from the directory alone, use search to locate the file and section.

When searching, prioritize precise keywords such as API names, configuration keys, component names, commands, and error messages.loci_search_files For queries , use an array and pass in 1–10 complementary queries at a time; results are returned grouped by query.library_ids It can also be multiple document library IDs; the two arrays can be used in combination. When the product or framework path is known, pass path_prefix to narrow the scope.

The tool will automatically relax in the order of “all words match → any word matches → title or URL path contains keywords.” Based on retrieval_mode and fallback_used , determine whether the results have been relaxed; if there are still no matches after relaxation, try a small number of synonyms, full names, or abbreviations, and do not immediately traverse the entire document library.

Search language

Use the top-level loci_get_library_tree returned by languages as the basis for the search language; do not read representative files just to detect the language. For example, when it contains zh or zh-CN , use Chinese concepts such as “响应式原理”, “依赖追踪”, and do not search only with English translation words.
API names, class names, function names, configuration keys, CLI commands, and original error text remain as-is and are not translated.
When multiple related expressions need to be looked up, put the keywords corresponding to the document language into the same queries array, for example {"queries":["响应式原理","依赖追踪","副作用"]}。
languages contains only und or the file language does not match the body text, determine the language based on the directory title, and if necessary include both the possible document language and English keywords in queries .

Reading strategy

When the target file is determined from the directory, read that file directly.
After a search hit, use the returned section_id to read the complete section; when details matter, do not answer based only on the search summary.
Only read multiple files in a batch when the question involves multiple concepts.
Use only when the returned content is incomplete next_offset to continue reading.
Stop retrieval once sufficient evidence is obtained, and distinguish document facts from Agent inferences.

Obtain missing document libraries

Querying the cloud public catalog is a read-only operation and does not require user confirmation. Use the technical name, official domain, or project name to call loci_list_cloud_libraries：

When a match for pages > 0 is found, explain the cloud document library name, source URL, and page count, and after obtaining user confirmation call loci_pull_cloud_library. Pulling will access the network and modify the local database.
Ignore 0-page cloud candidates; do not treat "an empty library exists" as having obtained documents.
When there are multiple possible matches, first narrow the scope based on official sources and project versions; if it cannot be determined, let the user choose.
When the cloud has no available matches, the query or pull fails, there are still no files after pulling, or the user does not choose to pull, find the project's or vendor's official documentation entry point, verify domain ownership, explain the name and URL, and after user confirmation call loci_add_library to create a document library and perform the first crawl.
The user's refusal of a cloud pull does not equal consent to crawl the official website; this is another choice that modifies local state and requires separate confirmation.
After acquisition is complete, use the returned local document library ID to enter the catalog, search, and reading workflow.

When the user has explicitly requested to pull, add, or crawl a specific document source, treat the corresponding operation as already confirmed and do not ask again. When it cannot be confirmed whether the source is official, do not add it and first ask the user to decide.

When calling loci_add_library , use the product base values:auto, 1000 pages, root path, and let source-level concurrency and the GitHub size limit inherit the global settings. MCP does not read CLI recent creation preferences. When the target documents are known to be at a fixed path or the user has limited the scale, directly pass override values such as scope_path、page_limit . The same domain and the same path will be reused; different paths of the same domain can have separate libraries. GitHub repositories are uniformly normalized by auto and the root path, with no need to pass web mode or path scope.

When an existing local library contains files, continue using the local content even if the cloud is inaccessible, and explain that it may not be the latest version. Cloud updates or pull failures must not delete usable local content.

Crawl and sync confirmation

Treat cloud pulls, new crawls, and proactive syncs as operations that modify local state and access external services. Before calling loci_pull_cloud_library、loci_add_library or loci_sync_libraries , explain the target and obtain user confirmation; when the user's current request has already explicitly requested the corresponding operation, no further confirmation is needed.

loci_sync_libraries is only used for web document libraries that already exist; non-existent document libraries must be obtained by cloud pull or by adding an official entry point. Do not sync the document library for every question; suggest syncing only when the user requests the latest information, the document library has not been successfully updated for a long time, local results are clearly missing, or it may be inconsistent with the official website.

When the user has authorized syncing, but another tool or Agent may have already started the task, first use library_id to call loci_get_sync_status。sync_status=syncing to follow the existing task, and do not start a second crawl in parallel; when it is truly necessary to wait in the current call, call loci_sync_libraries on the same document library and set wait_for_completion: true. Loci will reuse the task in the current MCP host, and cross-process calls are prevented from duplicate writes by the document source lock.

The synchronous response returns only the total number of failures, a breakdown of reasons, and a small number of samples. When you need the full failure details, take the returned run_id and call loci_list_sync_failures to read them in pages;library_id is for real-time status, andrun_id is for the history of a specific sync. Do not repeatedly start a sync just because the summary omitted the remaining failures.

Versions and conflicts

First confirm the dependency or tool versions actually used by the current project.
Prefer documentation that matches the project version.
Treat updated_at as freshness information for the local cache, and do not regard it as proof that the content applies to the current version.
When multiple local documents conflict, compare versions, directory locations, and source_url。
When the conflict cannot be resolved, search the official website online to verify in real time, and explain the conflict to the user.

Boundaries

When the domain of the final source_url matches an already confirmed official domain, the content may be treated as an official source.
For shared hosting domains such as github.ioand Read the Docs, also verify the organization, repository, or path ownership.
Do not equate an official source with version applicability or up-to-date content; still check the project version and sync time.
When official documentation exists, do not proactively add third-party mirrors.
Without user confirmation, do not add or proactively sync documentation libraries.
Only add public HTTP/HTTPS documentation that can be accessed without logging in; do not attempt to provide accounts, Cookies, Tokens, verification codes, or Cloudflare bypass solutions.
Do not add Hash Router documentation sites that rely on Fragments to distinguish pages.
When a single file or section is sufficient, do not read the entire documentation library.
Do not claim that using official documentation can completely eliminate errors or hallucinations.