agentleFS
flowleap-aiflowleap-ai/flowleap-cli/skills/flowleap-shared/SKILL.md

flowleap-shared

Skill1 starsChanged 4 months agoMITView on GitHub

Shared reference for every FlowLeap skill — authentication (OAuth device flow, fl_pat_ personal API tokens), credential storage, config precedence, global flags, and output formats. Trigger when a FlowLeap skill runs in a chat client with the FlowLeap connector or in the FlowLeap Patent AI app, when a FlowLeap command needs credentials set up, a global flag explained, config file locations, or output-format guidance; for the overall command map start from the `flowleap` skill.

  • Reads credentials
  • Installs packages

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 1 is distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Very specific:

    Every authenticated request sends Authorization: Bearer <credential> — either a session JWT from the OAuth device flow or a long-lived …

    line 96
  2. Very specific:

    When using FlowLeap as an AI agent, always pass --json for reliable parsing.

    line 142
  3. Very specific:

    Every request also sends the Client version header (X-FlowLeap-Client: cli/<version>).

    line 208
  4. Very specific:

    Agent-mediated sequence: run flowleap --json doctor.

    line 268
  5. Very specific:

    Use --dry-run before executing mutating operations

    line 364
  6. Very specific:

    Add --dry-run-redacted when the request contains an unpublished invention, claim, document text, URL, or search query that should not enter …

    line 365
  7. Very specific:

    Search queries are written by you, locally — an unpublished invention description never has to leave the machine to become a query (see …

    line 367
  8. Very specific:

    Use --verbose to inspect request details (credentials are redacted)

    line 370
  9. Distinctive:

    Never include credentials in commit messages or logs

    line 371

≈ “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

FlowLeap CLI — Shared Reference

Shared authentication, configuration, and global-flag reference used by every other FlowLeap skill. For the overall map of commands, skills, and workflows, start from the flowleap skill.

Chat clients and the FlowLeap Patent AI app

Two hosts run these skills without the CLI. In both, never run a flowleap … command and never tell the user to run one: call the tool that the table below names for the command.

auth, doctor, setup, init, keys, config, skills, upgrade, api, health, and mcp have no tool in either host. Global flags (--json, --dry-run, --output) do not apply: a tool call always returns the JSON envelope. Never ask for a key value in the chat. The key-gate doctrine in flowleap-keys (a gated office is a user-action stop) applies in both hosts; only where the user adds a key differs.

Chat clients with the FlowLeap connector

In claude.ai, Claude Desktop and mobile, Cowork, and ChatGPT, FlowLeap is a connector to the hosted MCP server. These clients have no shell.

  • Call the tool of the same name through the connector. The connector lists the same registry as flowleap tools list: the same tool names, input schemas (snake_case parameters), success envelope, and error codes.
  • Sign-in is the connector's OAuth. The user connects FlowLeap in the client's connector settings. In place of health, call server_info: it reports the backend's configured providers and available tools.
  • Patent-data keys are stored keys. The CLI forwards the keys kept on the user's machine; a chat client has no keys to forward, so the backend uses the stored key the user added on the FlowLeap Patent-data keys page (https://www.flowleap.co/en/dashboard/keys). When a tool answers a key gate, relay that page (the error's keysPageUrl and nextStep, when present).

The FlowLeap Patent AI app (firm OS and desktop)

The app runs the office tools in its own process on the data keys of the firm or of the desktop user. It has no flowleap command for you to run. The office tools need no FlowLeap sign-in; the paid tools need FlowLeap Data, which the firm administrator or the desktop user sets up outside the chat.

  • Office tools are native, under the table names with no prefix (search_patents, get_bibliography, get_us_grant, ocr, …). The app also has compare_claims and read_pdf (OCR of a workspace file).
  • Paid tools need FlowLeap Data. patent_analytics, the patstat_* tools, get_fulltext, and server_info exist only as mcp__flowleap__<name>, and only when the firm or the user has FlowLeap Data. US claims come from mcp__flowleap__get_claims: the native get_claims has no US source, and its answer names that tool. When a paid tool is not in your tool list, tell the user that the step needs FlowLeap Data, and continue with the native tools.
  • Data keys are the firm's or the desktop user's. The app's data keys are the Patent-Data Keys (EPO OPS, USPTO ODP) and the Semantic Scholar and Mistral OCR keys. When a tool answers that its key is missing, relay its message, which names the connector, and add: on the desktop the user adds the key in Settings > Patent data connectors; on the firm OS the firm administrator sets the keys for the whole firm, and an attorney cannot change them there. The flowleap.co keys page does not apply in the app.
  • No network outside the tools. Shell commands have no network, so use the shell only for local files, such as a skill's references/. The app has no web search or web fetch tool.
Command familyTool(s)Notes
ops biblio / claims / description / family / legal / abstractget_bibliography, get_claims, get_description, get_family, get_legal_status, get_abstractget_family is the INPADOC extended family; --resolve-npl is resolve_npl: true
ops register-biblioget_register_biblioEP only: representatives of record, opponents
ops register-searchsearch_registerEP Register CQL (query, range); the one search with a representative index (re=), opponent (op=), name in any role (nm=, surname-first — use it when a role index returns 0); EP applications only
patent search, ops searchsearch_patentsprovider: "epo_ops", CQL
uspto searchsearch_patentsprovider: "uspto", Lucene
uspto application / grant / continuityget_us_application, get_us_grant, get_continuity
uspto transactions / assignments / foreign-priority / adjustment / attorneyget_transactions, get_assignments, get_foreign_priority, get_patent_term_adjustment, get_attorney
uspto documents / document-textget_application_documents, read_application_document
citation search / forward / statssearch_office_action_citations, search_enriched_citations, get_citation_statscitation novelty is search_office_action_citations with category: "X", examiner_cited_only: true
EPO forward citations (no command)get_citations
patent examiner-baselineexaminer_baselineThe tool returns the same JSON.
academic search, nplsearch_academic, search_npl
npl-workget_npl_workone cited paper: DOI, OpenAlex id or citation string
analyticspatent_analyticsApp: mcp__flowleap__patent_analytics, FlowLeap Data only
ocrocr
patstat portfolio / query / docspatstat_portfolio, patstat_query, patstat_docsApp: mcp__flowleap__ prefix, FlowLeap Data only
patstat graph resolve / cpc / patent / applicant / technology / neighborhood / path / explainpatstat_resolve, patstat_cpc, patstat_patent, patstat_applicant, patstat_technology, patstat_neighborhood, patstat_path, patstat_explainApp: mcp__flowleap__ prefix, FlowLeap Data only
tools run <name>the same names

The one-call verbs (summary, compare, timeline, figures, convert-number) map the same way; their table is in the flowleap skill.

Authentication

Every authenticated request sends Authorization: Bearer <credential> — either a session JWT from the OAuth device flow or a long-lived personal API token (fl_pat_…).

Environment variable overrides (highest priority):

  • FLOWLEAP_API_KEY — personal API token (fl_pat_…)
  • FLOWLEAP_TOKEN — Bearer token
  • FLOWLEAP_BASE_URL — API base URL

The login, token minting/listing/revocation, and 401 self-heal commands live in flowleap-auth. Patent-data keys (EPO OPS / USPTO ODP BYOK) live in flowleap-keys.

Global Flags

FlagDescriptionDefault
--jsonShorthand for --output jsonfalse
--output <format>Output format: json, table, humanhuman
--base-url <url>API base URLhttps://api.flowleap.co
--api-key <key>Override stored API key (fl_pat_…)—
--token <token>Override stored token—
--dry-runShow request without executingfalse
--dry-run-redactedRedact sensitive values from dry-run output; requires --dry-runfalse
--verbose, -vShow request/response detailsfalse

Configuration

Config is stored in ~/.config/flowleap/config.toml. Credentials live separately in ~/.config/flowleap/credentials.toml (written mode 0600).

flowleap config set base-url https://api.flowleap.co
flowleap config get base-url

Config Precedence

CLI flags > environment variables > config file

Output Formats

  • --json (or --output json) — Machine-readable JSON (best for agents)
  • --output table — Formatted table
  • --output human — Human-readable text (default)

When using FlowLeap as an AI agent, always pass --json for reliable parsing.

Subscription, Rate Limits & Exit Codes

Patent data runs on the Tools facade — the single agent surface, reached as /v1/tools. Every data command POSTs to a named tool there; the per-source provider routes they used to call are retired endpoints (see the endpoint_gone row below). All of it requires an active plan — every new account starts a free 7-day trial period at sign-up, no card — and shares a limit of 60 requests/minute/user. doctor, health, auth, and keys test work without a subscription, so setup can always be diagnosed.

Error envelopes carry additive hints — subscriptionHint (402, has upgradeUrl, needs a human), providerKeysHint (missing/rejected EPO/USPTO patent-data keys, or the trial's shared data budget spent for today — needs a human), rateLimitHint (429, has retryAfterSeconds), and endpointGoneHint (410, { requiresUpgrade: true, successor?, reason?, message }).

Branch on codes, never on message text. Backend codes come from a closed registry and never change once shipped; wording is freely editable by policy, so matching text can invent a verdict that is not there. A providerKeysHint with code provider_keys_required is a user-action stop for that office, never an exhausted route: do not retry, do not invent keys, and do not substitute web-scraped patent data for the gated office — searches and single-document reads alike. The keys are free from each office. Read the gate, never infer it: only the explicit gate codes mean gated, so an empty result, a truncated payload, or a 5xx stays an ordinary dead route with the normal fallbacks. Full doctrine (proceed-then-ask, keyless pivot, resume): flowleap-keys.

Exit codeMeaning
0Success
1Generic failure
2Usage error (bad flags/arguments)
3Auth required (HTTP 401, or no credential configured at all) — log in or set FLOWLEAP_API_KEY
4Subscription required (HTTP 402) — surface subscriptionHint.upgradeUrl to a human
5Not found (HTTP 404)
6Rate limited (HTTP 429) — back off per rateLimitHint.retryAfterSeconds
7Network failure reaching the backend
8Endpoint gone (HTTP 410 endpoint_gone) — this build calls a retired endpoint
9Patent-data keys required/rejected, or the trial data budget exhausted — see providerKeysHint; a human must add keys, never retry

Exit 9 is the key gate, and only the key gate. It is the code behind provider_keys_required / provider_keys_invalid / trial_budget_exhausted, on data commands and on keys test / keys set alike, so a first-run key problem is distinguishable from a bad query without parsing the envelope. Treat it exactly as the providerKeysHint doctrine below says: a user-action stop for that office. The trial_budget_exhausted variant (backend ADR 0017) is the soft one — its hint carries resetsAt (next UTC day), so with the user's blessing an agent may also wait it out; the user's own free keys lift it permanently. Success envelopes warn before the wall: a trial_data_budget_low entry in body.warnings means finish the current work, then surface the key ask.

Exit 3 also covers the local auth guard. A command that needs a credential and finds none fails before anything is sent; its --json envelope is { "ok": false, "error": { "message": …, "code": "unauthenticated" } }. That code is the only machine-readable signal for the failure an agent hits before it ever reaches the backend — branch on it, not on the message.

Exit 8 is not a retry. A retired endpoint is permanently removed and a retired path is never reused, so the same call will never succeed again. Read endpointGoneHint.successor for where the capability moved, run flowleap upgrade, then flowleap skills update — an upgraded CLI with stale skill files walks straight back into the same 410.

Every request also sends the Client version header (X-FlowLeap-Client: cli/<version>). It is observational only — logged as stale-client and route-usage evidence, never used to reject a request — so it is nothing to configure or work around.

Reachability — flowleap health

flowleap --json health        # liveness
flowleap --json health api    # readiness; carries the backend's apiVersion

Both are public: no subscription, no patent-data key, no provider call. Use one of these (or flowleap --json doctor for the full checklist) to test whether the backend is up. Never probe reachability with a search command — a search costs a provider call and can fail for reasons that have nothing to do with reachability (no subscription, a key gate, a bad query), so it answers a different question than the one you asked.

Readiness — flowleap --json doctor

Doctor is the machine-readable onboarding contract. Its JSON always carries:

  • ready: bool — backend reachable AND authenticated AND no blocking next step pending. Stricter than ok, which keeps its reachability-only meaning.
  • nextSteps — the pending onboarding steps in dependency order (empty array when complete). Steps already covered — e.g. a provider with a stored key (validate source: "stored"), or one the server has its own keys for — are omitted. Each step:
{ "id": "store-epo-keys", "actor": "agent",
  "title": "Store the EPO consumer key and secret",
  "run": "flowleap keys set epo --key <k> --secret <s>" }

Stable step ids (public contract): auth-login (human), mint-personal-token (agent — pending while auth is only a session token with no fl_pat_ personal token), obtain-epo-keys (human), store-epo-keys (agent), obtain-uspto-key (human), store-uspto-key (agent; human, with the keys page url, when the office rejected the stored key), verify-keys (agent), refresh-skills (agent — installed skill files were written by an older CLI and still teach retired commands).

A step carrying advisory: true is worth doing but blocks nothing right now, so it does not count against ready. Only mint-personal-token is advisory: a session token works today and merely expires later, so an otherwise-green machine exits 0 with it still listed. Act on advisory steps; do not treat one as a reason the machine is not ready.

Exit contract: doctor exits 0 iff ready, else 1 — with the checklist JSON always fully emitted first, so flowleap doctor && <work> gates pipelines without parsing. An unreachable backend still emits the checklist from local state (offline diagnosis works); keyValidation.source says whether provider verdicts came from the server ("server") or fell back to local key presence ("local", with a note). keyValidation.providers ({ epo, uspto }) gives, per office, the validate source verbatim — user (forwarded key), stored, server or none; null when that office was not checked, and null for both on the local fallback.

Agent-mediated sequence: run flowleap --json doctor; for each step in nextSteps, execute actor: "agent" steps yourself via their run command, and relay actor: "human" steps (title + url) to the user; re-run doctor until ready is true. One exception: run a store-epo-keys / store-uspto-key agent step only with keys the user gave you without being asked. Otherwise relay the FlowLeap Patent-data keys page (https://www.flowleap.co/en/dashboard/keys; CLI and chat client only) — never ask for the key value in the chat (see flowleap-keys).

Updating the CLI

flowleap upgrade (alias flowleap update) updates the CLI itself, detecting the install channel from the running binary and acting accordingly: npm runs npm i -g flowleap@latest, an install.sh/raw binary self-updates in place (downloads the platform release asset, verifies its sha256 against checksums.txt, atomically swaps), and a cargo install prints the cargo install --git … --force command. --check (and --json/--dry-run) report { channel, currentVersion, latestVersion, updateAvailable, command } with no side effects, so agents branch on the result. The daily update notice and flowleap doctor both point here.

Installed skill files are copies, so an upgrade leaves them behind. A raw-binary self-update refreshes them with the new build; on every other channel run flowleap skills update after upgrading. Until you do, the skill files being read document retired commands — flowleap doctor reports a stale install as a ✗ carrying the refresh-skills next step.

flowleap upgrade --check --json
flowleap upgrade

Office coverage of the text tools and the family-member workaround

Office coverage is a property of a tool: the offices it answers for, and from which source. The three text tools serve two offices from EPO OPS and US claims from BigQuery. The other document reads (ops biblio, family, legal, abstract) are worldwide bibliographic; get_citations is worldwide DOCDB citation data; get_patent_image serves EPO OPS images for the offices EPO OPS holds.

  • ops claims / get_claims: EP and WO from EPO OPS; US from BigQuery, in English only.
  • ops description / get_description: EP and WO from EPO OPS. US description is not served.
  • get_fulltext (no command): probes the EPO OPS holdings only, so it answers for EP and WO. A negative probe means EPO OPS holds no text, not that no text exists.

Eight offices have bibliographic, family and legal-event depth and no text source: CN, JP, KR, CA, AU, FR, DE and GB. Backend ADR 0024 adds no source until a customer names an office, so never call one of them "pending".

Family-member workaround for a publication at one of those offices, two steps:

  1. flowleap --json ops family <number> / get_family (the extended INPADOC family) to find the EP, WO or US member.
  2. flowleap --json ops claims <member> or ops description <member> / get_claims or get_description on that member.

Two limits apply, always. The member's claims are not the office's claims: use them for prior art and reading only, never for a freedom-to-operate, infringement or validity verdict on that office's right, and label the text as the member's. The member's text must itself be served: only EP, WO or US text is served, and US description is not.

How likely the workaround is: the share of A filings 2015 to 2024 whose extended family has an EP, WO or US member, measured on PATSTAT 2026 Spring. Tell the human the share before you spend a family read.

OfficeShare with such a member
CA95%
AU88%
FR60%
DE55%
GB54%
JP48%
KR38%
CN13%

The share for CN is low. For a CN prior-art question go to the abstract, the bibliography and the citations first, and try the family after.

The served failure. A text read for an office with no text source answers FULLTEXT_UNAVAILABLE (HTTP 404, exit 5; a data verdict, never retry). Under error.details, reason is no_source and the workaround field beside it is { tool: "get_family", note }: act on that field, not on the message text. A US publication the BigQuery table does not hold answers no_source with no workaround (a holding gap). Reason not_configured means the server has no BigQuery configured: a server configuration gap, no workaround, and server_info shows it on the US get_claims row (officeCoverage).

Safety

  • Use --dry-run before executing mutating operations
  • Add --dry-run-redacted when the request contains an unpublished invention, claim, document text, URL, or search query that should not enter logs
  • Search queries are written by you, locally — an unpublished invention description never has to leave the machine to become a query (see flowleap-patent)
  • Use --verbose to inspect request details (credentials are redacted)
  • Never include credentials in commit messages or logs

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.