fast-search
Skill44 starsChanged 4 days agoApache-2.0View on GitHub
Low-latency academic paper discovery for search-bar queries. Infer hidden entities, use one logical batch through the installed web-search skill to resolve likely paper titles, run one bounded PaperHub keyword/title/citation graph, and return up to 20 precision-first papers in metadata.json. Use when a user or product needs the Veryfast paper-search workflow rather than iterative literature research.
- Reads credentials
In this repository12 other files it gives its agents.
- academic-research-guidanceSkill
- agentic-searchSkill
- design-research-validationSkill
- find-skillSkill
- literature-reviewSkill
- pdf-evidenceSkill
- plugin-createSkill
- precise-literature-searchSkill
- project-literatureSkill
- research-idea-partnerSkill
- scholarseed-product-operationsSkill
- web-searchSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
19 rules. About 0 are common, 9 are distinctive, and 10 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.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 19
Never persist a paper abstract.
- Very specific: line 34
Read SETUP.md only when configuration is missing or a request fails.
- Very specific: line 36
Use PaperHub plus the separately installed $web-search skill.
- Very specific: line 55
Run tools/doctor.py once only when readiness is genuinely unknown.
- Very specific: line 80
Before the $web-search batch, say that the request is being analyzed and key paper entities are being resolved.
- Distinctive: line 82
After web search and before the single runner call, say that candidate entities have been resolved and PaperHub retrieval and ranking are …
- Distinctive: line 84
After the runner succeeds, use the final response as the completion update.
- Distinctive: line 120
Do not substitute a more familiar, similarly titled preprint or journal version.
- Distinctive: line 128
Do not add web batches or agent-driven page fetches.
- Very specific: line 133
If the user instead asks for related work around a linked paper, explicitly set best_target.required: false.
- Distinctive: line 140
Do not repeat successful queries through another provider, open result pages, or make a second logical web batch.
- Distinctive: line 167
Before submitting the plan, check that its bounds reflect the user's intent.
- Distinctive: line 174
Do not open web pages, use a pool-inspection tool, make another logical web batch, or run a model-based selection pass.
- Very specific: line 177
Use a file-editing tool, not a shell command, to write one JSON plan at WORK_DIR/.fast-search-plan-<short-topic>.json.
- Distinctive: line 212
After writing the structured plan, make exactly one shell call containing only stable file paths:
- Distinctive: line 234
Never interpolate credentials.
- Very specific: line 263
Do not equate missing metadata.json with a successful zero-result search.
- Very specific: line 264
If neither a usable locator nor a verified title can be obtained, use the file-editing tool to write RESULT_DIR/search_failure.json …
- Very specific: line 268
When the runner cannot find a verified target, it exits nonzero and writes the same failure file with error: fast_search_target_not_found.
≈ “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.
Files
Fast Search
Return up to 20 relevant papers in metadata.json, aiming for a useful,
well-covered result within the search budget. A short or empty result under a
hard publication window is a last-resort outcome, not the target. This skill exposes exactly one
workflow: Veryfast. It does not perform iterative gap filling or generate a
narrative report.
Never persist a paper abstract. Abstracts may be used transiently inside the
single runner process for relevance scoring, but metadata.json, session state,
round traces, plans, caches, and diagnostic artifacts must omit the abstract
field and its text. Do not copy an abstract into another field.
Paths and connectivity
SKILL_DIRis the absolute directory containing this file. Use absolute paths for bundled tools.WORK_DIRis the user's current working directory. Write results only underWORK_DIR/fast-search-results/<short-topic>/; append a timestamp rather than overwrite existing results. The one transient structured plan may be a hidden sibling underWORK_DIR; the runner consumes it after success.- PaperHub authentication comes only from
SCHOLARSEED_API_KEY; configuration is loaded bytools/localconf.py. - Read
SETUP.mdonly when configuration is missing or a request fails. If a sandbox policy blocks local networking, request narrowly scoped approval. - Use PaperHub plus the separately installed
$web-searchskill. Always start each logical public-web batch through that skill; do not choose direct runtime Web Search in place of an available skill route. The host owns the provider route required by that skill: theofficialprofile (provider: official-api) first, thenativeprofile (provider: codex-native) only after a structured unavailable/failed result or artifact-publication failure, then thebrowserprofile (provider: visible-browser) only when the runtime permits full access. For official and browser, require a deliveredweb-search-result.jsonartifact, gate onschema: shushen.web_search.v1, and decide the search outcome from itsstatus, not the provider process exit code.completedandemptyare terminal successes;unavailable,failed, andaction_requiredare not successful candidate sets. Treat a nonzero publication command, missing or unreadable artifact, schema/query/provider mismatch, or malformed envelope as a failed leg. Never infer entities from status logs. A successfully completed direct runtime Web Search that occurs despite this priority is an acceptable compatibility result and must not be repeated through another provider. If a direct runtime call is unavailable or fails, return immediately to the$web-searchofficial profile within the same turn. - Run
tools/doctor.pyonce only when readiness is genuinely unknown; add--liveonly for a needed network check. Trust its booleans and never print environment values.
For Skill-style deployment, explicitly load both $fast-search and
$web-search into the same turn; do not rely on implicit skill discovery. This
priority, fallback, and result contract applies identically with or without the
App Server Worker.
For a $web-search native-profile fallback, require exactly one object between
<shushen_web_search_results> and </shushen_web_search_results>. Validate the
strict native envelope: schema = shushen.web_search.v1; status =
completed or empty; provider = codex-native; query exactly matches the
requested query; candidates contains at most 20 exact
{title,url,description} objects; and error is null. If native Web Search
cannot return that envelope, continue to the browser profile. Across all three
providers, consume only the common candidate core. Accept provider extension
keys and do not reject a visible-browser candidate solely because its
description is empty; title and a direct HTTP(S) url are load-bearing.
User-facing progress
For an interactive Skill invocation, emit only these concise commentary updates at the existing action boundaries:
- Before the
$web-searchbatch, say that the request is being analyzed and key paper entities are being resolved. - After web search and before the single runner call, say that candidate entities have been resolved and PaperHub retrieval and ranking are starting.
- After the runner succeeds, use the final response as the completion update; include its reported PaperHub runner elapsed time when available, the metadata path, and paper count.
Match the language explicitly requested by the user; otherwise match the language of the user's query. Keep each update to one sentence. Do not expose reasoning, planned query strings, or raw events. Include elapsed time only when the host or completed runner already exposes it; never estimate it. Do not add a clock command, model call, search, wait, or any other action solely to generate progress. The UI may also show provider tool cards; these short semantic updates complement those cards without changing the retrieval graph.
Veryfast workflow
The whole path is defined here; do not inspect tool source/help or configuration before running it.
1. Plan once
Infer hidden named methods, datasets, projects, standards, and likely landmark
titles from the full clue bundle. Make one logical public-web batch with three
complementary queries, even when the surface topic is explicit; its purpose is
to resolve concrete paper titles. Start with three explicit $web-search
invocations concurrently when the host supports it, and follow the skill's
official → native → browser route for each query. A successful direct runtime
Web Search may satisfy the same logical batch as a compatibility path:
- the full rare clue bundle plus
paper; - the central comparison/relationship plus
original study paper; - the rarest mechanism, population, dataset, or method clues plus
paper title.
For a single-paper lookup, use this same batch to resolve the target instead:
the clean article URL, its DOI/identifier when available, and its canonical
title or article identifier. When the input is an explicit full paper title,
preserve that title in best_target.title and the exact-title query, with
required: true; use the given title verbatim in the existing web batch too.
Do not substitute a more familiar, similarly titled preprint or journal version.
For URL/DOI inputs, the linked identifier determines the requested version.
A publisher article URL (not just arXiv) names
the paper itself unless the user asks for related work. Remove tracking
parameters such as utm_* and fragments, but keep article IDs in query parameters.
DOIs embedded in a URL can be reused; Nature /articles/<id> maps to
10.1038/<id>. For opaque publisher URLs, resolve the title from web evidence
matching that URL; never guess a DOI from an arbitrary article number.
Do not add web batches or agent-driven page fetches. The runner can verify the
input URL/DOI directly from scholarly metadata in parallel with PaperHub. If
the batch cannot resolve its title, keep best_target.required: true, omit its
title, and use the known identifier as a bounded keyword query; never invent a
title or stop solely because web search/PaperHub did not resolve the link.
If the user instead asks for related work around a linked paper, explicitly set
best_target.required: false; do not treat the seed as a mandatory answer.
Respect hard publication periods in the existing searches. A cutoff does not mean "newest papers only": core and founding papers inside the period remain useful. A soft preference for recency is not a hard cutoff.
Do not repeat successful queries through another provider, open result pages, or make a second logical web batch. Extract clean scholarly titles from the batch, then produce 3–6 short English relevance concepts and an ordered PaperHub plan. Order both keyword and title queries from highest to lowest expected value; the runner's safety guard keeps the first four keywords and first eight titles if the plan accidentally exceeds the Veryfast budget:
- for a direct paper lookup (a publisher/arXiv article URL, ID, DOI, or full title), first identify the single canonical title from a web candidate that matches that identifier or title; do not substitute generic identifier/topic queries for this exact-title probe;
- 3–4 complementary keyword queries for the central relationship and compared method/evidence families. For an explicitly named method/application request, use Boolean clauses to keep that relationship together; PaperHub OR-matches an unqualified list of words. Write Boolean operators as uppercase AND/OR/NOT; quote multiword method/task phrases and use OR for alternative names, not AND;
- 6–8 exact or near-exact title queries for the most likely core entities and founding papers within any hard date window; do not invent titles to fill the budget;
- prioritize queries that jointly explain multiple rare clues, but retain bare canonical-title queries for central entities;
- interpret publication requirements from the full request, including negation,
exceptions, and whether recency is mandatory or merely preferred. Translate
hard bounds into inclusive top-level
date_start/date_end(YYYY-MM-DD), oryear_start/year_endfor whole years. Omit bounds for soft preferences or unconstrained requests. The runner validates and executes these fields; it does not interpret natural-language dates or repair omitted constraints. Before submitting the plan, check that its bounds reflect the user's intent.
Topic and method relevance remain part of semantic query planning and the existing ranking, not a literal-name eligibility gate. Use the bounded queries to cover complementary formulations of the same request, including genuine method aliases where useful, without relaxing the user's hard requirements.
Do not open web pages, use a pool-inspection tool, make another logical web batch, or run a model-based selection pass.
Use a file-editing tool, not a shell command, to write one JSON plan at
WORK_DIR/.fast-search-plan-<short-topic>.json. Do not create RESULT_DIR
yourself. Put the full user query and concepts in the plan so no user-controlled
text needs shell quoting:
{
"query": "FULL_USER_QUERY",
"inspect_concepts": ["entity", "mechanism", "method", "dataset"],
"year_end": 2025,
"queries": [
{"mode": "keyword", "query": "highest-priority relation"},
{"mode": "title", "query": "Highest-Priority Paper Title"}
]
}Preserve up to four important paper-page/DOI URLs from this same web batch in
web_papers: [{"title":"CANONICAL_TITLE","url":"EVIDENCE_URL"}], prioritizing
the requested paper. Include each title as a planned title query. Use direct
scholarly sources, not news, snippets or guessed URLs; provide no abstract or
claimed bibliographic fields. The runner verifies these records independently
and adds only papers missing from PaperHub to the existing ranking. This is a
bounded metadata lookup, not another model/web-search round. Do not gather extra
URLs or pad this list when the batch lacks useful evidence.
For a direct paper lookup with a resolved title, also set
"best_target":{"title":"CANONICAL_TITLE","required":true} and include that
canonical title as a title query. The runner copies the bounded plan into the
result and consumes the external plan only after successful publication; an
invalid or failed run leaves the source plan available for diagnosis without
creating partial paper results.
2. Run once
After writing the structured plan, make exactly one shell call containing only stable file paths:
scholarseed-skill-python "SKILL_DIR/tools/quick_search.py" \
--plan "PLAN_FILE" \
--consume-plan \
--output-dir "RESULT_DIR"For a direct paper lookup, supply the resolved best_target. The runner reserves
the verified target as Tier 1 top-1, even if the topic ranker would place it lower.
The eligible pool includes independently verified external metadata when
PaperHub did not retrieve the paper. A single verified paper is a valid direct
lookup result; do not pad it with unrelated papers. It fails closed only when
neither path verifies an eligible target. Conflicting identifiers are rejected;
if identifiers are missing, an exact match of the web-verified title is allowed.
For an unresolved URL/DOI, the runner may obtain the canonical metadata itself.
External records use explicit non-PaperHub IDs and retain real DOI/URL and
source evidence. Never mix a preprint's PaperHub ID/date with a journal version's
DOI or promise that retrieving metadata also downloads the full text.
Never interpolate credentials. The runner validates and bounds the complete
plan before creating state, runs in a private staging directory, and publishes
paper results only after success. It executes the single serial PaperHub graph,
automatically tracks references from two ranked anchors, and selects papers
using relevance, exact-title match, citation provenance, and diversity. Within
Tier 1 it first promotes a paper whose arXiv ID, DOI, or full title is explicitly
present in the user query, then the agent-declared best target, and otherwise
the highest relevance score. For topic searches, the optional declared best
target never changes tier membership. Only a required single-paper target has
the reservation described above. Remaining candidates retain their
existing order. It writes compact metadata.json without abstracts and does
not generate a report. The runner adds server-side date bounds and checks all
keyword/title/citation dates before pooling and anchor selection, without extra
requests. Do not append date clauses yourself. Insufficient date evidence is
excluded; counts are reported in search_summary.retrieval_date_filter and
date_exclusions. Do not relax dates or pad a shortfall with older papers.
A valid empty result still produces metadata.json. If no verified matches were
found, state that this search found none under the stated dates, not that no such
papers exist, and suggest a user-approved reformulation. Do not relax the dates
or silently start more rounds. Report a shortfall as such, not as full coverage.
Report completion only after an actual successful runner tool result supplies
result.output and result.selected_count; a plan, intended command, or
simulated transcript is not execution evidence. If execution is unavailable or
fails, report that failure instead of inventing a file path or count. On success,
return the runner's path and count without rereading the file or running another
command.
Failure contract
Do not equate missing metadata.json with a successful zero-result search.
If neither a usable locator nor a verified title can be obtained, use the file-editing
tool to write RESULT_DIR/search_failure.json containing
{"schema":"fast_search.failure.v1","error":"fast_search_target_unresolved"}
and report the problem without inventing a title or running PaperHub.
When the runner cannot find a verified target, it exits nonzero and writes the
same failure file with error: fast_search_target_not_found; leave it intact.
Explain that this search could not retrieve/verify the requested paper, not
that the paper does not exist or is definitely not indexed. Suggest a full
title/DOI or trying later. Other execution failures must also be reported as
failures. Never fabricate metadata or repeat the bounded graph to hide failure.
The low-latency target assumes the persistent Worker and its bundled default model configuration. A direct invocation inside an already-running interactive Codex session follows the same retrieval graph, but session startup, model, and reasoning settings can increase latency.
Follow-ups
Veryfast is a one-shot product response. Do not extend a completed run with extra search rounds. Start an independent fresh run only when the caller asks for another search.
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
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.

