agentleFS
htlin222htlin222/openevidence-skill/SKILL.md

openevidence

Skill17 starsChanged 3 months agoApache-2.0View on GitHub

Install, manage, troubleshoot, and use the canonical openevidence-mcp server. Use when the user asks to set up or update OpenEvidence MCP, check its relay or login, query OpenEvidence for clinical evidence with citations or BibTeX, retrieve an OE answer or shared conversation, search prior answers, manage collections, or change conversation sharing.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. htlin222/openevidence-mcp★ 83same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

The file

Show its rules and text

We split this skill into the rules it gives an agent

23 rules. About 0 are common, 9 are distinctive, and 14 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 14

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use the canonical htlin222/openevidence-mcp implementation.

    line 8
  2. Distinctive:

    Never reimplement the OpenEvidence API, send direct HTTP requests to its private API, or fall back to an exported-cookie Python client.

    line 10
  3. Very specific:

    If the user wants to install, update, inspect, clean up, or uninstall the MCP, run the matching command from scripts/oe-mcp.sh.

    line 14
  4. Very specific:

    If the user wants OpenEvidence data and the oe_* MCP tools are available, call those tools directly.

    line 15
  5. Very specific:

    Read references/tools.md when choosing among the complete tool set.

    line 17
  6. Distinctive:

    Do not claim setup is complete before the extension is loaded and the client is reconnected.

    line 39
  7. Distinctive:

    Use the two checks for different questions:

    line 43
  8. Very specific:

    Call oe_health first to test the local pipeline.

    line 45
  9. Very specific:

    Call oe_auth_status only after health succeeds to verify that the browser tab is actually logged in.

    line 46
  10. Very specific:

    Call oe_health when connection state is unknown.

    line 54
  11. Very specific:

    Call oe_auth_status when login state is unknown or health alone is insufficient.

    line 55
  12. Very specific:

    Call oe_ask with the user's question.

    line 56
  13. Very specific:

    Call oe_article_get with that ID.

    line 58
  14. Very specific:

    Use oe_public_get for an OpenEvidence /ask/<id> link when the user wants readable question-and-answer turns.

    line 65
  15. Very specific:

    Treat oe_article_set_access as a consequential write:

    line 67
  16. Distinctive:

    Never make a conversation public if it contains PHI, patient identifiers, medically sensitive details, secrets, or content the user has not …

    line 70
  17. Distinctive:

    When there is any doubt, keep the conversation private and ask the user to remove sensitive content or confirm the disclosure.

    line 72
  18. Very specific:

    Use collection create/add/bulk-apply tools only when the user asks to change organization.

    line 74
  19. Distinctive:

    Do not delete the retained database or remove the browser extension unless the user separately and explicitly requests a full wipe.

    line 84
  20. Distinctive:

    Keep the MCP server and extension implementation in the upstream repository.

    line 88
  21. Distinctive:

    Do not copy upstream TypeScript, extension code, protocol code, or API payload logic into this skill.

    line 89
  22. Very specific:

    Do not use cookies.json as the primary setup.

    line 90
  23. Distinctive:

    If install/update output asks for an extension reload or MCP reconnect, repeat that requirement clearly to the user.

    line 91

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

OpenEvidence MCP

Use the canonical htlin222/openevidence-mcp implementation. It sends OpenEvidence requests through a localhost relay and a Chromium extension running inside the user's logged-in browser tab.

Never reimplement the OpenEvidence API, send direct HTTP requests to its private API, or fall back to an exported-cookie Python client. Plain server requests are blocked by bot detection. If the MCP tools are unavailable, install or repair the MCP instead.

Route the request

  1. If the user wants to install, update, inspect, clean up, or uninstall the MCP, run the matching command from scripts/oe-mcp.sh.
  2. If the user wants OpenEvidence data and the oe_* MCP tools are available, call those tools directly.
  3. If the user wants OpenEvidence data but the tools are unavailable, do not substitute a direct HTTP client. Install the MCP only when the user asked for setup or authorizes the prerequisite; otherwise explain the missing dependency and ask them to approve installation. Complete the manual browser step and reconnect the MCP client before attempting the query.
  4. Read references/tools.md when choosing among the complete tool set.

Resolve the skill directory containing this SKILL.md, then invoke:

bash <skill-directory>/scripts/oe-mcp.sh <install|update|status|cleanup|uninstall>

Honor OE_MCP_DIR when the user wants the upstream checkout in a non-default location. The default is ~/openevidence-mcp.

Install and connect

For first-time setup, run scripts/oe-mcp.sh install. The wrapper checks Node.js 22+, clones the canonical repository if necessary, and delegates the build, extension, and MCP-client registration to upstream make all.

Then instruct the user to complete the browser action that cannot be automated:

  1. Open chrome://extensions in Chrome, Edge, Brave, Arc, Vivaldi, or Opera.
  2. Enable Developer mode.
  3. Choose Load unpacked and select <openevidence-mcp>/extension/dist.
  4. Stay logged in to https://www.openevidence.com in that browser.
  5. Reconnect or restart the MCP client so it discovers the newly registered server.

Do not claim setup is complete before the extension is loaded and the client is reconnected.

Verify health and authentication

Use the two checks for different questions:

  • Call oe_health first to test the local pipeline. It checks the relay daemon, extension connection, protocol version, and recent activity without contacting OpenEvidence.
  • Call oe_auth_status only after health succeeds to verify that the browser tab is actually logged in. This performs a network round trip to /api/auth/me through the relay.

If oe_health says the daemon is down, trigger an MCP call or run the status command and follow its hint. If the daemon is up but the extension is disconnected, ask the user to load/reload the extension and keep the Chromium browser running. If oe_auth_status fails, ask the user to sign in to OpenEvidence in that same browser.

Ask and retrieve

For a new clinical question:

  1. Call oe_health when connection state is unknown.
  2. Call oe_auth_status when login state is unknown or health alone is insufficient.
  3. Call oe_ask with the user's question. Keep the default fire-and-forget behavior unless the user explicitly needs a blocking one-shot call.
  4. Capture the returned article_id and pending status.
  5. Call oe_article_get with that ID. Use wait_for_completion: true when the current turn should wait for the finished answer; otherwise fetch it later.
  6. Present the OpenEvidence answer as sourced clinical evidence, preserve its citations, and distinguish it from independent medical advice.

To continue a thread, pass the prior article ID or /ask/<id> URL as original_article_id to oe_ask. Prefer oe_answers_search before spending another question when an earlier fetched answer may already cover the topic.

Read links, share, and protect sensitive data

Use oe_public_get for an OpenEvidence /ask/<id> link when the user wants readable question-and-answer turns. Public links can work anonymously; private links require the connected logged-in relay session.

Treat oe_article_set_access as a consequential write:

  • Change access only when the user explicitly asks.
  • Never make a conversation public if it contains PHI, patient identifiers, medically sensitive details, secrets, or content the user has not reviewed for disclosure.
  • State that public: true makes the link readable by anyone who has it.
  • When there is any doubt, keep the conversation private and ask the user to remove sensitive content or confirm the disclosure.

Use collection create/add/bulk-apply tools only when the user asks to change organization. Prefer read-only list, get, summary, search, and unsorted tools for inspection.

Manage the installation

  • install: clone if needed, build the server and extension, and register supported MCP clients.
  • update: fast-forward the upstream checkout, rebuild, and re-register. Then require the user to reload the extension and reconnect the client.
  • status: show upstream versions, relay health, and client registration.
  • cleanup: reap orphan relay processes and stale temporary state while keeping the installation and user database.
  • uninstall: unregister clients, stop daemons, and remove generated builds. It intentionally keeps ~/.openevidence-mcp data and the browser extension.

Do not delete the retained database or remove the browser extension unless the user separately and explicitly requests a full wipe.

Boundaries

  • Keep the MCP server and extension implementation in the upstream repository; this skill is only an orchestration and usage layer.
  • Do not copy upstream TypeScript, extension code, protocol code, or API payload logic into this skill.
  • Do not use cookies.json as the primary setup. The logged-in browser extension is the default authentication path.
  • If install/update output asks for an extension reload or MCP reconnect, repeat that requirement clearly to the user.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.