SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsokp-search

okp-search

Data & analytics

View repository

Updated 10-16 01:35

About this skill

okp-search — Knowledge Search Skill

CRITICAL — Before starting, you MUST confirm that the okp CLI is installed and can connect to the API:

npm install -g @markbangwu/okp
okp domains   # 确认 API 可达

When to use

  • The agent needs to find knowledge (characters, art styles, operation manuals, social media shares, etc.).
  • When answering user questions, structured knowledge in the Open Knowledge Protocol needs to be retrieved.
  • Traverse relationships between concepts (via links).

Read permissions

Public domains are readable by all authenticated users. Private domains are only readable to explicitly invited reader / writer and the creator host visible; global admins also have no read bypass and must first accept the invitation. For write permissions, see okp-import; this skill is read-only.

Retrieval loop (strictly in this order)

Step 1: Determine the domain

okp domains              # 列出所有领域
okp domains -q <keyword> # 按名称模糊找领域

Returned fields:domain、concept_count、has_readme、visibility。 concept_count=0 indicates that a README has been defined but there is no concept yet.

Private domains will not appear in list, search, sample, links, or export results before an invitation is accepted.

Step 2: Read the domain README (mandatory)

Each domain's README defines: what the data is, which types exist, which frontmatter fields can be filtered, and how to search.

okp domain <domain>

Do not skip the README and search blindly. Different domains have different fields and usages; parameters must be based on the README.

Step 3: When unfamiliar, sample first

okp sample --domain <domain> --limit 5

Look at a few real data entries, confirm what title / tags / frontmatter look like, and then decide how to search.

Step 4: Perform precise search according to the README

Based on the schema and How to use in the README, choose the appropriate combination:

# 列出某个 domain 的 concept（无 query 即按 domain 浏览；默认 limit 50）
okp search --domain <domain>
okp search --domain <domain> --limit 100
okp search --domain <domain> --limit 50 --offset 50

# 结构过滤（domain / type / tag 等）
okp search --domain <domain> --type <type>
okp search --domain <domain> --tag <tag>

# frontmatter 过滤（字段名以 README 为准）
okp search --domain <domain> --filter <field>=<value>
okp search --domain <domain> --filter <field>=<value> --sort date:desc

# 文本 / 语义查询
okp search "<query>" --domain <domain>
okp search "<query>" --domain <domain> --type <type>

Principles:

  • To browse which concepts exist under a domain → okp search --domain <domain>(can add --limit / --offset pagination)
  • If you know the specific entity name → text query
  • If you know the structured field (who posted it, which group, which wiki) → --filter, more accurate than plain text
  • Multiple fields can be combined, all with AND
  • For time-series data, use the README-recommended --sort
  • Exact character/substring matches take priority; semantic results serve as a supplement (implementation details are transparent to the user and need not be expanded in the answer)

Step 5: Light list → close reading

Search and sample return a summary list (id, title, description, tags, frontmatter).
Do not directly use the list as the body text. Select the 1–3 most relevant ones and then get:

okp get <id>

ProhibitedBulk fetching the body.

Step 6: Navigate along relationships

okp links <id>

Returns outgoing (what it references) and backlinks (what references it).

Step 7: Rewrite when unsatisfied

  1. Read the domain README again and confirm the fields were used correctly
  2. Change the query wording (full name / abbreviation / Chinese and English)
  3. Loosen or tighten type / tag / filter
  4. Switch domains or use sample to re-scout

Common flag reference

flag Purpose
--domain / -d Limit the domain
--type / -t Limit the type
--tag Limit tags (repeatable)
--filter key=val Filter by frontmatter fields (fields are based on the README)
--sort Sort, such as date:desc、updated_at:asc、title:asc
--limit / -n return count

Result fields

Field Description
id Path-style ID:domain/type/slug
domain / type Domain and type
title / description Title and summary
tags Tags
frontmatter Extended fields (vary by domain)

The full body is only obtained via okp get <id> .

Out of scope for this skill

  • Knowledge import / write permissions / invite code → okp-import
  • domain README maintenance → okp domain <domain> --set readme.md
  • OKF bundle export to local → okp export <domain> --out <dir>