Skip to content

docs(skill): prefer MCP server / CLI over grep for external-agent search #264

Description

@sebastianbraun25

Problem

skills/openkb/SKILL.md currently tells external agents (GitHub Copilot, Claude Code,
Cursor, etc.) to fall back to grep -r for keyword search and to read wiki/index.md in
full for taxonomy/document discovery. Neither is ideal at scale: grep has no
relevance ranking (a document that happens to repeat a generic word often can outrank one
that's actually about the topic), and reading the full index.md costs an increasing
number of tokens as the KB grows, with no guarantee the agent's attention lands on the
right one-liner (see discussion in the referenced chat thread for concrete before/after
examples).

Since #260/#261 (CLI) and #262/#263 (MCP server), the exact same taxonomy-browsing and
tiered-search capability the internal openkb query/openkb chat agent uses is now also
reachable from outside the OpenKB process — but the skill doesn't mention either yet.

Vorschlag

Update skills/openkb/SKILL.md to prefer, in order:

  1. The MCP server (openkb-mcp) if the calling agent has MCP tool access — list_taxonomy
    then scope-restricted search_wiki, mirroring the internal agent's own search strategy.
  2. The CLI (openkb list-taxonomy/openkb search) as a fallback when no MCP client is
    configured, still both cheaper and more precise than raw grep.
  3. Direct grep/file reads only as a last-resort fallback when neither is available.

No behavior change to the underlying tools/CLI/MCP server themselves — this issue is
skill-documentation-only.


This issue was drafted with the assistance of an AI assistant.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions