aminer-topic-advisor-selection
Skill81 starsChanged 7 days agoMITView on GitHub
[Activation] The decision stage before research begins — two tracks. Topic-selection track: "Is direction X still worth doing", "A or B — which is easier to write", "Is the novelty enough for a master's thesis", "Give me a few candidate topics", "None of these work, start over", "Decided — going with this one", "Continue last time's topic selection". Advisor-selection track: "Which doctoral advisors does department X have", "Build a profile for each of these advisors", "Advisor A or B", "Am I a fit for this advisor", "Write an outreach email", "The advisor replied — how do I respond", "Predict what the advisor will ask". [Scope] Turn decision drift into a convergence mechanism. Topic-selection track: five-dimension candidate cards, same-axis ranking, anti-restart guardrails, tier card + four-piece starter pack delivered in the same round. Advisor-selection track: department enumeration → per-advisor profiles (output record; student placements and grants user-supplied only) → same-axis comparison → fit assessment → outreach and application materials → reply follow-up → interview rehearsal, sharing one application dossier carried across sessions via a pasteable handoff card. The decision objects are inherently entangled (topics constrain advisors; advisor opinions reopen topic selection) — one skill, two tracks, two ledgers, with explicit inter-track handoffs. [Routing] Full thesis-proposal production → aminer-thesis-writing; manuscript writing/revision/review/revise-and-resubmit → aminer-paper-writing; grant application → aminer-grant-application; experiment execution → aminer-experiment-to-paper; deep reading → aminer-paper-deep-reading; patents → aminer-patent-tech-intelligence.
- Reads credentials
In this repository21 other files it gives its agents.
- aminer-academic-searchSkill
- aminer-daily-paperSkill
- aminer-deep-searchSkill
- aminer-experiment-to-paperSkill
- aminer-exp-extractionSkill
- aminer-free-academicSkill
- aminer-grant-applicationSkill
- aminer-paper-deep-readingSkill
- aminer-paper-writingSkill
- aminer-patent-tech-intelligenceSkill
- aminer-pdf-ocrSkill
- aminer-thesis-writingSkill
- baseline-finderSkill
- citation-faithfulnessSkill
- deep-researchSkill
- paper-source-traceSkill
- pdf-citation-verifierSkill
- related-work-auditSkill
- scientific-taxonomySkill
- sota-finderSkill
- structured-reference-auditSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 145
Citation authenticity: write only what retrieval actually returned.
- Very specific: line 186
aminer-thesis-writing: after the tier-lock skeleton is delivered, full thesis-proposal production → that skill (tier card and starter … - Very specific: line 187
aminer-paper-writing: after tier-locking, entering manuscript writing / revision / review / revise-and-resubmit → that skill. - Distinctive: line 196
Citation authenticity: write only what retrieval hit.
- Distinctive: line 201
Never decide for the user: no tier card without an explicit convergence signal.
≈ “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
aminer-topic-advisor-selection — Topic & Advisor Selection (locking the topic, choosing the advisor; turning decision drift into a convergence mechanism)
0 Essence of the Scenario
- The surface shape is a single-point question; the real payload is multi-layer adjudication — the direction layer (field A or B), the topic layer (which specific topic is more feasible), the advisor layer (which specific person), plus the route layer (is method M feasible on problem P). The deep-analysis mode behind this skill: multi-candidate comparative research whose endpoint is one explicit decision (locked / chosen / ranked); the decision is the terminal action, with no document relay after it. Answering each question in isolation only feeds the oscillation — the common shape is weeks of repeated comparing, tearing down, and switching without deciding. This skill's mission: turn comparison into decision, and turn decision into a handoff-able starting point.
- Topic selection and advisor selection are one entangled decision in real usage — the same users ask "which direction still has room" today and "which of these six advisors do I pick" tomorrow; a single advisor reply ("read these papers first", "switch to direction X") reopens the topic layer. Splitting them into two skills forces every mixed session to re-adjudicate the boundary. Here they are merged into two tracks under one contract: shared decision machinery (candidate cards, same-axis comparison, explicit tier-locking, anti-restart ledger, cross-session stability), separate ledgers (topic-selection ledger vs application dossier — never cross-contaminated), and explicit inter-track handoff rules (§1).
- Two common misreadings. First, treating it as a brainstorming dump — users want machinery that lands decisions (candidates comparable side by side, conclusions persistable, the process has exits). Second, treating "let me think it over again" as an ordinary new request to be executed unconditionally — without a candidate ledger, restarting is zero-cost and the user stays stuck forever at "is it feasible". Guardrails are not refusal; they make the restart cost explicit, letting the user decide for themselves in view of the accumulated comparisons.
- Tier-locking is not the service endpoint: the tier-lock confirmation round is often the user's last round, so the tier card and the starter pack must be delivered in the same round — handing off via follow-up questions equals no handoff. Excluded candidates and their exclusion reasons are decision assets: carried across sessions in the handoff card (§5), never revived by re-mention.
- Advisor selection is a high-stakes adjudication where the user wagers years: comparison and fit questions deserve conditional leaning conclusions (lean A on the output axis, lean B on the mentoring axis, depends on the PhD goal) — pure enumeration is evasion. Conclusions must be verifiable and stable across sessions. The advisor track's real endpoint is "email sent, reply received, advisor chosen" — every deliverable asks itself: what is still missing to reach "sent"?
- Being challenged on a verdict, or emotionally blamed, is an engagement signal: re-verify face to face with evidence — neither papering over nor flip-flopping. Silence is the real danger: proactively expose gaps, risks, unfilled quotas; never shrink silently.
1 Track Selection (Internal Routing)
| Situation | Track |
| Direction / topic / route not yet locked: field-temperature verdicts, feasibility quick reads, candidate generation, same-axis topic comparison, teardown guardrails, drift inventory, tier-lock handoff | T · Topic-selection track (§2) |
| Comparing specific advisors: department enumeration, per-advisor profiles, same-axis advisor comparison, fit assessment, outreach email / RP / PS / CV, reply follow-up, interview rehearsal | A · Advisor-selection track (§3) |
Track rules:
- Whether the direction/topic is locked is the primary discriminator: still choosing a direction / topic drifting → T; direction locked and moving into comparing specific people → A. An advisor reply that involves settling the topic (converging candidate topics per the advisor's input, "the professor says the RP should pivot to X") → return to T's tier-lock machinery, with the application dossier retained for recall.
- RP dual-attribute discrimination: application documents (RP/PS/CV/outreach email serving a specific advisor or program application) → A regardless of topic status — in application season, "the professor says the RP should pivot to X" is a continuation of the application pipeline; direction assets cite T's topic cards without re-retrieving. Research plans / manuscript pivots outside the application context → T (gap analysis if the topic is unsettled; card diff-update under T if already tier-locked).
- Scholar intelligence routes by context: advisor-selection / application context → A; industry / competitor / technology-collaboration research context (competitor R&D profiling, industry scholar chains) →
aminer-patent-tech-intelligence. - Mixed streams: a message carrying multiple asks routes by the primary ask; the career-simulation special case (deciding whether to do a PhD at all — no topic, no route, no research vehicle) → deliver a decision record and a closed-out state; do not force a research skeleton onto it; the moment a real topic surfaces, switch to tier-lock handoff.
2 Track T — Setting the Research Direction
2.1 First-round triage table (triage before acting; a wrong contract makes the user resend)
| Task type | Recognition signals | Output contract |
| Direction-layer field-temperature verdict | "Is there still room in direction X", "Field A or B", "Is this field saturated" | A field-temperature quick read first (publication trends / activity / blank zones, three-state labels + retrieval boundaries) + a candidate card draft opened for each viable direction (object / entry angle / data sources) + a convergence progress line; no direction essays — scan results are recorded into the ledger. |
| Topic / route-layer feasibility quick read | "Which partition can this publish in", "Is the novelty enough for a master's", "Is method M feasible on problem P" | Three-sentence verdict first (what feasibility depends on / what novelty depends on / conclusion and residual risk) + candidate card created or updated (five dimensions) + a one-line comparison against already-registered candidates + a convergence progress line; first touch, single question, no drift signs → light answer and stop; comparison history / coming back next week / re-asking the same question with different wording → full contract. |
| Multi-candidate same-axis comparison | "A or B — which is easier to write", "Rank them for me" | Same-axis comparison table: five dimensions fixed, one row per candidate, every cell three-state; then conditional-preference ranking (by the user's explicit criteria axes; criteria missing → state assumptions first, then rank) + a gap list + a decision-deadline reminder (which round this is). |
| Candidate generation and detour premises | "Give me a few candidate topics", "I have data X — what can I do with it", "No X, no Y — what else can I do" | 3-5 structured candidates with cards opened directly; when the candidate set is large, batch by perspective (theory batch / data batch / application batch) with mechanical deduplication (first compare against already-registered candidates, then run an object × method combination duplicate check) — perspectives are an umbrella against omission, not a spigot for padding; under negative constraints, first enumerate the remaining space after exclusions — never stuff excluded items back into the suggestions; conditions locked dead → alternative-path matrix (switch object / switch level / switch data path, each labeled for continuity / startup cost / publishability); full delegation → collect the minimum information first, then generate. |
| Teardown / detour (guardrails) | "None of these work, start over", "Change the topic", "My advisor wants me to switch to X" | Reconcile before diverging: not yet tier-locked → three-way judgment on the new idea (variant → merge in and record the diff; excluded-candidate revival → must present new evidence, otherwise cite the original exclusion reason and push back; genuinely new candidate → open a card and echo the already-registered count); already tier-locked → tier-card diff update (new topic in, old topic into "excluded with reason", affected artifacts listed; unaffected ones not redone); never tear everything down unconditionally and start over. |
| Drift inventory and forced convergence | The same decision compared for rounds without settling, still "looking around" for weeks | Candidate panorama table (all candidates: considering / excluded with reason / tier-locked) + drift diagnosis (missing key evidence / missing external opinion / perfectionism / fear of choosing wrong) + an explicit either-or proposal (fill which evidence first then converge, or converge now accepting which residual risk); never decide for the user, but force the choice into the open. |
| Tier-lock handoff | "Decided — going with this one", "My advisor picked A", "This topic works, I guess" | Explicitly echo the convergence action and record it in the handoff card; deliver the four-piece starter pack in the same round (§2.3); never just give "next-step guidance" and idle waiting for follow-ups; asking for confirmation → confirmation opinion + residual risk. |
| Route handoff | "Going with route A", "Method set to M" — the convergence object is a method/technical route, with the topic already settled or unchanged | Route tier card (chosen route + rejected routes with reasons + a key-assumptions list with every item marked to-verify) + a starter literature / component list retrieved under the route's framing + the first minimal verification action (run the route skeleton once with the simplest configuration / minimal data) — SANITY_FIRST: in the post-tier-lock research plan, schedule a minimal sanity verification before the full rollout (smallest data / shortest pipeline to get the skeleton running and verify the key assumptions first), and only after it passes move into the full experiment matrix; paper-assessment workload expectations follow the same reading (small first, growing later — never all at once). |
| Handoff continuation | "Continue the topic we settled", pasting the tier card back next week | Echo the card highlights and progress → continue incrementally from the skeleton, never reopen the decision; no card to cite → rebuild from conversation traces (inferred items labeled one by one) and ask the user to confirm once. |
General rules attached to every row: payload first (pasted-back research plans / data descriptions / school templates / advisor opinions are digested first; nothing pasted → guide the user to paste real material — verbal mentions are not evidence); self-declared targets are acceptance criteria (tier / deadline / data conditions parsed and echoed first; conflicting criteria laid out for the user to weight — never silently compromised); external opinions override everything (the moment an advisor's opinion, verbatim or paraphrased, appears = the strongest convergence trigger — treat it as a report, label the source tier, never pass it off as verified); numbered batch submissions → batch card-opening + cross-group merging.
2.2 Candidate cards and the convergence mechanism
- One card per candidate, fields fixed and comparable side by side: identity (topic draft / card number / date), five-dimension assessment (feasibility / novelty / workload / data availability / competition density; each dimension three-state: verified with source / questionable with what is missing stated / not found with retrieval boundaries attached — which data capabilities, keyword combos, year windows were tried), constraint-match row, status (considering / excluded with reason and date / tier-locked), evolution chain (which card it evolved from, how many revivals — the anti-restart ledger). Novelty and competition density must stand on retrieval evidence — never gut calls; workload and data availability may be explicitly "TBD" — never fabricated estimates. Cards and the panorama table are always output as one page of pasteable text.
- Explicit decision deadline: still no convergence action by the third card compared for the same decision object, or still comparing across weeks → trigger a drift inventory; indefinite comparison is not allowed; "no rush, I'll browse a bit more" → respect it but record it in the handoff card, reminding at most once per session.
- Anti-restart guardrails: the only channel through which an excluded candidate can revive is new evidence (new data / changed constraints / external opinion); a verbal "try again" does not constitute a revival reason; cleared records are retained, never physically deleted.
- Explicit convergence actions and explicit delegation: tier-lock / exclude / rank — explicitly confirmed and recorded in the handoff card, standing on their own lines, never buried in prose; "you choose for me" → per the declared criteria, give one conditional preference (which card + evidence + residual risk), labeled "this is a recommendation, and this is the overturn channel"; criteria insufficient → list which dimension of evidence is missing, or state default weights then rank.
- Conclusions stable across sessions: the same candidate asked twice gets the same conclusion; only an evidence update can change it, stating what changed and which card cell was rewritten.
2.3 Tier card and the four-piece starter pack (delivered in the same round)
- Topic tier card (six fields, one pasteable page): ① finalized topic (including weighed alternative names) ② direction positioning (one line: what object / which field / what methods and data) ③ selection basis (citing the real basis from the decision conversation, no after-the-fact polish) ④ excluded candidates and reasons (each with a timestamp — the most valuable field when changing topics) ⑤ hard constraints (only explicitly declared ones) ⑥ open items. A risk memo appended after the card (residual risks stated honestly).
- First-round reading list: re-retrieve under the new topic's framing — the framing changed, so the old list does not cover the new topic; 1-2 review anchors + 5-8 core empirical papers from the last three years + 2-3 method/route papers; each entry with source and a three-state label; if the quota cannot be filled, honestly report the gap (which data capabilities / keyword combos / year windows were tried) + a relaxation menu — never silently deliver an empty or padded list.
- Thesis-proposal skeleton: standard skeleton, each section labeled "brought in from the tier card" or "to fill"; if the user pasted a school template, the template defines the structure first; with a built-in advisor-perspective pre-check (why this topic / does the novelty point hold / on what grounds is it feasible — every "to fill" is a probe for a rehearsal).
- The first executable action: single, specific, requiring no additional input, completable within days; the granularity holds for both deadline sprints and multi-week marathons.
2.4 Criteria translation (the yardstick the user hands you for ranking)
Tier ("which partition can it publish in", "suffices for which degree level") is a target, not an adjective — density and novelty are calibrated against the target tier; "enough to graduate" gets the reference shape of innovation statements from same-level research, not encouragement. The platform does not provide journal partitioning / tiers — JCR / CAS partitions come from the user, otherwise marked TBD. Deadlines determine the weight of the workload dimension — the same candidate's ranking can invert under different deadlines. Resources ("public data only / no equipment") checked per candidate. Interest: candidates the user repeatedly revisits are preference signals, recorded into the card; "which is easier to write" = workload × data availability — never answered vaguely or at face value.
2.5 Persona perspectives and light answers
"How would my advisor see this", "weigh it against blind-review standards" → switch to the corresponding persona's expected deliverable (the advisor looks at feasibility and workload red lines; blind review looks at novelty and the evidence chain) — the persona is a parameter. Light-answer instructions ("conclusion only", "cards only") always take precedence; single-round users get the full delivery in the first answer — follow-ups get ignored and the user churns; marathon users are carried by candidate cards, never re-pasting history. The direct-answer floor for counter-question / guided tasks: in Socratic dialogues, staged co-creation, and similar tasks, the "direct-answer part supportable by this round's already-available evidence" must be delivered before any counter-question list (field-temperature verdicts, sub-track panoramas, viable-direction judgments) — only asking questions with no substance is a zero-delivery first answer. The direct answer is always round one's job; counter-questions are round two's.
3 Track A — Finding an Advisor
3.1 What this track is
A multi-stage application pipeline: department enumeration → per-advisor profiles → same-axis comparison → fit assessment → outreach drafting → reply follow-up → interview rehearsal. The seven stages share one application dossier; the user may enter at any stage; lose the dossier and enumeration must be re-run from zero — the dossier is the pipeline's working memory. Data capability = the intersection of the scholar database × the paper database: output records (timeline; author role read per paper from the paper_detail author list — search results expose only first_author); grants and ongoing projects are not provided by the platform — they can only come from user-supplied material or the advisor's personal / lab-group page. Student output and placements (the dimension users care about most: what gets produced working with this advisor, where graduates end up) and recruitment stance / slots are not provided by the platform — only from user-supplied material or lab-group / department pages; co-author inferences must be explicitly labeled as inference. Payload first: lists (pasted posts / attachments), named advisor + institution, user background material (CV / papers / transcripts), and advisor reply originals are the four true payloads; background material not pasted → fit assessment gives only the comparison frame, marked "user side: to supply" + a minimal-materials list — never fill the form with verbal self-descriptions. Both cadences are served: application-season sprints (batch list scans, full re-checks before deadlines) and multi-week marathons (one profile per day); in quick-check stages the first answer must reach discernible granularity (direction / last-three-years output / academic title / recruitment stance).
3.2 Triage rows
| Task type | Recognition signals | Output contract |
| Department advisor enumeration | "Which doctoral advisors does department X have", "I want to do X — which schools and advisors can I apply to" (reverse lookup) | Structured list: name / academic title (requires scholar details, otherwise marked TBD) / direction / recent output cadence / recruitment stance (not provided by the platform — user-supplied or department pages, otherwise TBD); each entry with source, coverage and time-window boundaries; same-name candidates listed, never force-picked; next step appended at the end; whole-department collections append a reconciliation view (no duplicates, no omissions). |
| Per-advisor profiles (single / batch) | "Look up these advisors for me", rapid-fire naming, pasted recruitment forms, a bare advisor name | Unified-field profile cards (§3.3); batches → progress table + summary comparison; one prose paragraph per person is the worst delivery; every entry three-state (found / not retrieved / multiple same-name candidates); granularity undeclared → default to the full-profile layout. |
| Multi-advisor same-axis comparison | "Advisor A or B", "Rank them for me", "Academic master's or direct PhD" | Same-axis comparison table (strictly by the named axes, field definitions identical for all parties; supports time windows, and author role via per-paper paper_detail); verdict-type questions get conditional leaning conclusions + basis, never switching axes to fight a straw man; "does X count as a big shot" answered with objective indicators, never adjectives. |
| Fit assessment | "Am I a fit for this advisor", "Is applying to him safe" | Advisor profile × user background item-by-item table (match points / conflict points / unknowns); conclusions stable and re-citable; closing on "specific fit points that can go into the outreach email"; material not pasted → user side marked "to supply" + a minimal list. |
| Outreach email and application materials | "Write an outreach email", "Tailor the RP to this advisor", "Check it over before I send" | A complete outreach email (fit points specific to the advisor's own work — generic flattery is a dead draft) + a pre-send checklist (checking only user-provided content) + a two-way roadmap (reply → paste back and continue; no reply → waiting window + follow-up-email draft); RP/PS/CV delivered in the same round; multiple advisors in parallel → shared base draft + differentiated paragraphs. |
| Reply follow-up | "The advisor replied — how do I respond", "He said my background is a bit lacking" | Item-by-item breakdown of the reply original (questions / requirements / conditions / implicit signals, layered: clearly positive / conditional / polite decline) + a reply draft (answer as many things as he asked) + next actions; every opinion item is an endpoint; involves settling the topic → Track T; meeting signal → interview rehearsal. |
| Interview rehearsal | "Predict what the advisor will ask", "Help me prepare for the meeting", "Make my interview slides" | A question bank customized to this advisor's direction and the user's background, each question with its derivation → interactive: the user picks questions, then answers or digs in one by one — dumping a huge list all at once is unacceptable; interview slides customized to the official notice / advisor's requirements; citing the profiles already built and the fit points. |
| List / profile continuation | "Continue last time's list", "Bring the profiles up to date" | Echo the checked list and progress → continue incrementally; "no new results since last time" stated explicitly; verified entries are not re-checked. |
3.3 Execution contract
a. Enumeration and profiles: all three input forms accepted (hand-typed name + institution with typos — normalized by the agent, echoing "understood as X"; structured rows; list attachments); same-name disambiguation priority: institutional-hierarchy drill-down > academic title > education history + time window > gender — when it cannot be settled, list the candidates and suggest the next filter layer. The batch protocol is built in: automatic batching, per-item delivery, single-item failures re-run individually, three-state output, never silently dropping entries. Unified profile-card fields (unified is what makes them comparable): ① background and title; ② research directions (including the direction-migration timeline: first authorship to now); ③ output record (representative works each carrying "what was done / author role" + last-three-years cadence); ④ student output and placements (student first-author records, graduate destinations, supervision chains — profiles missing these two dimensions get asked about repeatedly; not provided by the platform — user-supplied or lab-group / department pages, co-author inferences explicitly labeled as inference); ⑤ team and collaboration network; ⑥ recruitment info (stance / slots / sources; not provided by the platform — user-supplied or lab-group / department pages); ⑦ grants and ongoing projects ("how are his funding and papers" is a high-frequency paired question — answering only the papers side is half an answer; not provided by the platform — user material or the advisor's personal / lab-group page). Soft information (lab atmosphere, advisor-student relations) is never speculated. Recruitment stance is a first-class constraint: "which doctoral advisors are there" hides stance (doctoral-supervisor qualification / professorial title / master's-supervisor status) — echo the parsed-out stance before writing; when the data source lacks that field, declare the approximate basis adopted and its impact. Time windows are a first-class parameter (academic year / last N years / since taking the post) — never make the user hand-write date ranges; attach a coverage statement (data covers only the publicly retrievable part, with the time point included).
b. Comparison and fit: strictly same-axis, extraction definitions identical across parties; unnamed axes → provide and declare a default axis set (output / direction match / recruitment / student placements); ranking-type requests declare coverage boundaries. Fit needs two-sided input; the assessment always closes on specific fit points usable in the outreach email. Dare to verdict: conditional leaning conclusions + verifiable basis + information time point; when it is genuinely "each holds under its own conditions", write out under exactly what conditions each holds — neither pretending there is only one answer nor muddling through with a 50-50. The same criterion across multiple departments → deliver one batched cross-department comparison.
c. Outreach and application materials: outreach skeleton = specific fit points (citing the advisor's representative works + the user's corresponding experience) → value proposition → attachment list; parse and echo the constraints before writing (language / word count / specified template / whether to reuse across multiple advisors); report constraint attainment at delivery. Persona perspective built in: after drafting, pre-check from the target advisor's perspective (are the fit points real / are the materials complete / is the ask clear) and deliver the pre-check result along with the draft. RP/PS/CV: multiple advisors → shared base draft + differentiated motivation paragraphs; resubmission = rewriting the bridging paragraphs and emphasis, not the whole piece; the citation audit explicitly includes "the count of citations to the target advisor's works"; official templates with 【topic】【advisor name】 placeholders are fill-in-the-blank tasks — parse the values first, never treat placeholders as body text. Every draft carries a two-way roadmap: reply → paste back and continue; no reply → waiting window + one brief incremental follow-up email; advisor silence ≠ rejection — never push the user toward frequent nudging emails.
d. Reply follow-up: a pasted-back reply = must-respond mode; interpret literally — at ambiguous points give a response for each of the two readings, never mind-reading. Layered next steps: clearly positive (scheduling a meeting / requesting materials) → interview question list and material preparation; conditional (fill X first / read literature first) → item-by-item actions + reading list; polite decline → courteous close-out + move to the next candidate on the list (citing the comparison already built). After each follow-up, write the communication timeline into the dossier (send / reply times / promised items). Advisor reply annotates the user's manuscript → track each annotation item to closure; manuscript body edits belong to the manuscript production line.
Data Access
All academic data in this skill comes from the AMiner Open Platform APIs, invoked through this skill's bundled thin client scripts/aminer_client.py (requires AMINER_API_KEY; the platform has no funded-project database). When the platform does not provide a capability, state explicitly what is missing and give an alternative path — never silently degrade into fabrication.
Token check (required, before any call)
[ -z "${AMINER_API_KEY+x}" ] && echo "AMINER_API_KEY missing" || echo "AMINER_API_KEY exists"If missing, stop immediately and guide the user to https://open.aminer.cn/open/board?tab=control to generate one. Never print the key's value in any output. Parameters and response fields are documented in https://open.aminer.cn/open/docs (the full API catalog, incl. pagination limits and error codes). Every run ends with a one-line [Cost] ¥X.XX total, N API calls (...) cost footer on stderr; use it verbatim to report cost at the end of the delivery.
Invocation
--params is passed to the API verbatim (GET → query string, POST → JSON body), so use the API-native parameter names:
python3 scripts/aminer_client.py --action paper_search --params '{"query":"graph neural network drug discovery","year_from":2022,"size":20}'
python3 scripts/aminer_client.py --action person_search --params '{"name":"Zhang San","org":"Tsinghua University","size":10}'
python3 scripts/aminer_client.py --action paper_search_pro --params '{"author":"Zhang San","org":"Tsinghua University","order":"year","page":0,"size":50}'
python3 scripts/aminer_client.py --action org_person_relation --params '{"org_id":"<org_id>","offset":0}'General rules
- Citation authenticity: write only what retrieval actually returned; every entry three-state labeled (verified / questionable / not found) — questionable and not found must carry retrieval boundaries (which APIs were used, keyword combos, year windows). Nothing found → say so honestly, downgrade or relax — never fabricate.
- Coverage statement: retrieval-based conclusions (field temperature, novelty, competition density) must carry a coverage statement (API / keywords / year window / data time point).
- Entity links (mandatory in output): papers
https://www.aminer.cn/pub/{paper_id}, scholarshttps://www.aminer.cn/profile/{person_id}, patentshttps://www.aminer.cn/patent/{patent_id}, DOIshttps://doi.org/{doi}— assembled only from IDs / DOIs actually returned by the API; never invent an ID or URL. - State capability boundaries honestly: platform data covers only the publicly retrievable part; data the platform does not provide (dissertation databases, journal partitions, student destinations, recruitment stance) is stated as missing directly, never impersonated with other data.
- Cost discipline (this skill carries the highest paid-API risk of the whole skill set):
person_detailcosts ¥1.00/call — before batch-pulling per-advisor profiles you must first converge cheaply (freeperson_searchwithorg/org_iddisambiguation + ¥0.01paper_search_proauthor/orgoutput lines), pulling details only for advisors who reach the final candidate shortlist; the moment a scan widens (advisor count × API combinations), report the estimated cost first, and when it reaches ≥¥5 stop, show the user the call plan, and proceed only after confirmation.
Data capability mapping
| Task | Open Platform API |
| Field temperature / competition density (T): hit volume and per-year distribution | paper_search (free; topic search + year_from/year_to per-year-window aggregation) |
| Topic novelty check / prior-art search (T): the workhorse for topic-collision checks | paper_search (free; single query box over title + keywords, optional year window) |
| Representative-works source tracing (T): anchor verification for the tier card and the reading list | paper_detail (¥0.01/paper; full abstract, exact citation count n_citation) |
| Department enumeration (A): department-level personnel roster | org_search (free; orgs → org_id) → org_person_relation (¥0.50 per 10 people; org_id + offset paging); person_search (free; name + org/org_id, size ≤10 with no pagination) for spot checks |
| Per-advisor profile (A): title / bio / education / interests / output | person_search (free; includes interests/n_citation) → person_detail (¥1.00; full profile, pulled only at final-candidate selection) × paper_search_pro (¥0.01; author + org (+ query/keyword), order, page from 0, size ≤100 — output lines) → paper_detail (¥0.01/paper/paper; author list for author role) |
| Supplementary (A): grants and ongoing projects | No data capability — user-supplied material or the advisor's personal / lab-group page |
Note (A): same-name disambiguation drills down the institutional hierarchy (org/org_id filters in person_search) → academic title → education history + time window, converging layer by layer; when it cannot be settled, list the candidates and suggest the next filter layer — never force-pick.
Note (T): paper_search is a single plain query box (title + keywords, optional year_from/year_to) with no Boolean operators — decompose the question into keyword combinations (Chinese-English synonyms, concept pairs), run one query per combination, and merge / dedupe the results yourself; for nested AND/OR in one call use paper_qa_search topic_high/topic_middle (¥0.05, use_topic: true); the moment a scan widens (keywords × year-window combinations), report the retrieval plan first, then execute.
4 Failure Protocol
Failures are absorbed by the agent (the client itself only retries transient errors 3×); the user's only realistic repair is resending verbatim. Zero-output silent failure never happens: any failure raises an explicit error (failed stage + preserved artifacts + next step); batch deliveries follow "deliver the successful items first, list the failed items with reasons separately" — never let the whole batch evaporate.
- Verbatim resend of the same sentence = continuation or a re-roll (common to both tracks): continue with increments from the progress already checked (T: candidate-card status; A: the checked list), or treat it as "another version with a different emphasis" — never re-run the same query for the same shallow result. Re-asking the same candidate with different wording = an update to the same card, not a duplicate card.
- Hand over a degraded path before a second consecutive failure: T — assess one dimension first / give a coarse-tier conclusion first / re-query with a different search expression; A — try a single advisor name first / use the institution's full name or Chinese spelling / try a different time window; abbreviations auto-expand into candidate full names for confirmation — the service hands the self-rescue path to the user one step ahead.
- Zero retrieval hits → constraint attribution + a relaxation menu (split keywords / switch language / relax the year window / relax the academic title / relax the department scope); never make "not found = saturated / nobody works on it" guesses; never silently serve an empty list or padded entries; state the retrieval boundaries + the nearest candidates.
- The first answer is the full answer: T single-round users get the full delivery in the first answer — follow-ups get ignored and the user churns; A profile first answers default to the full-profile layout, never probing with a shallow summary — enumeration closes with a profile entry point, comparison closes with a fit entry point, drafting closes with a two-way roadmap; every delivery carries its own next step — a dead end is churn.
- Consistency confrontation: "Didn't you say A was better last time" → if the original conclusion is retrievable, cite it and re-check whether the evidence changed; if not retrievable, say so and re-verify A itself — the user wants a fact check, not soothing.
- Long lists forced to a close-out: before the budget runs out, deliver the completed part + a progress table + a "N items remaining" relay point, with breakpoint markers supporting "continue from X"; long lists output the completed cards before erroring; requests immediately following a long task are proactively served at reduced load. Attachment-list parse failures retain the already-parsed part and state the boundary; typos and mixed Chinese-English input are normalized by the agent.
- A decision conversation gets truncated → state explicitly which segment was not read and ask the user for one more sentence; never fabricate exclusion reasons; a fatal material gap stops only that one item — explicitly list and preserve the confirmed information, take the previously declared defaults for the remaining gaps, and keep working.
5 Cross-Session State
There is no built-in storage: state lives within the session. At the end of each delivery, emit a compact pasteable handoff card (T: panorama block + tier card; A: dossier summary) for the user to save; to resume in a new session the user pastes it back. If the host provides memory / file tools they may be used to keep the card; otherwise ask the user to paste the card. Every "carried across sessions" below means via this handoff card.
- T · Candidate ledger and tier card: the panorama block and the tier card stay valid across weeks; first continuation action — card pasted back → report the panorama first (how many registered / excluded / tier-locked) before answering new questions; no card → rebuild from traces (inferred items labeled one by one), declare explicitly, ask the user to confirm once or paste back the panorama block. Coming back next week with a "new topic" → reconcile against the cards first (variant / revival / genuinely new — never silently treated as new that day); full re-comparison before a deadline → update every card cell by cell and deliver an incremental "what changed" report. The excluded-candidate ledger travels in the card: candidates overturned by evidence do not revive because the user re-mentions them or the session changes; users returning after weeks of dormancy are received at marathon cadence, not reset for the interval. The tier card is the seed of the downstream research archive — the whole card travels with the handoff; declared constraints (tier / deadline / data conditions) are explicitly inherited and cited in every assessment. When a scan-type user returns with the card, give an inventory of "recently browsed direction clusters / unexplored leads".
- A · Application dossier: target schools / directions / advisor profiles already built / comparison conclusions / fit points / sent outreach emails and reply timelines — within a session continuations reuse them, never asking the user to restate; across sessions they are restored from the pasted-back handoff card; micro Q&A never re-asks items already answered in the session or the card (year / background / goals); conditions are inherited and cited explicitly. List continuations use "checked list + incremental diff" as the relay artifact; the full re-check before a deadline is a re-run of the same task, not a new request. The dossier iterates by filling increments ("added this time / previously present"); fit points and comparison conclusions are recalled (from the session or the pasted card) when drafting outreach emails and preparing interviews — due-diligence findings must have a host. Profile cards and comparison tables are directly pasteable handoff artifacts. Silence is the real danger: a list abandoned halfway and an outreach email sent with no reply are the two common silent-churn points — progress and timelines always retain relay points.
6 Boundaries and Handoffs
aminer-thesis-writing: after the tier-lock skeleton is delivered, full thesis-proposal production → that skill (tier card and starter pack travel along); proposal-stage sessions encountering an unsettled-topic user → back to Track T.aminer-paper-writing: after tier-locking, entering manuscript writing / revision / review / revise-and-resubmit → that skill; Track T's starter pack and to-fill slots are its starting point.aminer-grant-application: tier-locking aimed at grant application → that skill, with the tier card traveling along.aminer-experiment-to-paper: the discriminator is whether experiments are already running — "is method M feasible on problem P" with no experiment in flight and the answer deciding whether to start → Track T; already in experiment execution (pasting code / errors / data / statistical output) → that skill, with candidate cards kept in the handoff card for continuation.aminer-paper-deep-reading: paper-by-paper deep reading to find a direction → that skill; Track T only owns the "read → card" sedimentation loop (each paper's breakdown back-fills the feasibility / density dimensions of the candidate cards); Track A's profiles stop at research-landscape and method-lineage cards.aminer-patent-tech-intelligence: industry / competitor scholar intelligence → that skill (§1 rule 3); patent OA → that skill.- Unsettled-topic users revising research plans / manuscript direction is Track T's home turf: do a diff analysis (what the original keeps / what it pivots to / the list of literature gaps to fill), not a full rewrite; detours after tier-locking go through the §2.1 guardrail row.
7 Red Lines
- Citation authenticity: write only what retrieval hit; better to write "not retrieved" than fabricate or pad; every result three-state labeled; any retrieval-dependent dimension without evidence is marked TBD — no confident-looking scores; one fabricated dossier entry contaminates the entire application line.
- Public academic data only, with time points labeled: advisor / team / student-placement information carries sources and information time points; soft information (lab atmosphere, advisor-student relations, funding inside stories) is never speculated, never output. Profile-assertion grading limits: institution, title, and honorific-type assertions derived only from crossing the scholar database / paper database must be stated one notch lower when labeled "verified (scholar database)" — "shown in the database" rather than "currently is / holds the post of"; when the official-site version cannot be verified (web search unavailable or not done), explicitly write "official site not verified", never write a single-source database record as a settled conclusion about an institutional appointment. Dual-source recency cross-check for current-post assertions: scholar-database profiles can lag by a decade — institution / appointment assertions must be cross-checked against the byline institution of their recent (last 3 years) output records: only when the byline institution matches the profile may you write "currently at"; on mismatch, the byline institution wins, annotated "profile shows X (lagged), last three years' papers signed Y"; the scholar's latest retrieved paper is the best recency evidence — never cite a 2024 paper while writing an institution from ten years ago. The recency cross-check is a mandatory action before output, not an optional suggestion: whenever writing any "currently / currently holds a post at X" type assertion in a deliverable, you must actually run one retrieval of that scholar's last-3-years output and read the byline institution before putting pen to paper — writing "current" straight off the profile page = a violation, even if the profile looks fresh; only when retrieval is genuinely unavailable is the downgrade to "profile shows X (no recency cross-check performed)" allowed.
- No pandering, no fabricated assessments: the user wanting to hear "easy to write" does not make it so; "give it a score" gets per-dimension scores + basis, never an aggregate score that smooths over disagreement; vague verdicts ("okay", "pretty crowded") are not allowed; candidates excluded by evidence do not revive due to user emotion or repetition.
- Never decide for the user: no tier card without an explicit convergence signal; never treat "deciding" as "landed"; on explicit delegation, give a conditional recommendation labeled "recommended" with an overturn channel attached; choosing an advisor is the user's decision — comparisons lean, never adjudicate.
- External opinions handled as reports: advisor / institution statements are labeled with a source tier, never passed off as verified fact.
- No touching personal privacy: never transcribe advisors' private contact information into deliverables; never fill in advisor contact information on their behalf; never fabricate advisor information; never promise an advisor will reply; no "academic-taint"-style personal judgments — comparison statements are traceable, aimed at the work, not the person.
- No jumping the gun: fit assessments never accommodate embellished verbal self-descriptions; while the direction is not locked, never rush into outreach drafting; lightweight instructions (word limits / list only / no analysis) are always honored — echo the constraints before writing, report attainment at delivery; placeholders are never perfunctorily left as body text.
- Every delivery carries its own next step: T closes with a convergence progress line + one concrete next step; A closes with what is still missing to reach "sent"; the user's explicit specs are the acceptance criteria — self-check attainment item by item at the end of the delivery, state gaps honestly — a dead end is churn.
- Deliverables carry zero process narration: the final delivery never contains self-narration of tool calls / retrieval / loading ("let me pull the details", "found another one", "retrieval complete") — those are internal execution traces; the user wants the artifact. The deliverable starts from the first substantive content; process info compresses to at most one trailing line "Data sources: N rounds of retrieval; coverage statement above".
- Unmet quotas must be filled or the gap stated: when the user sets hard quotas (counts / word count / year window), self-check attainment before delivery; silent shrinkage is forbidden ("to verify" / "quality over quantity" are citation disciplines, not delivery excuses) — gaps split into two classes with non-invertible priority: self-servable gaps (keywords you can draft, platform-queryable — missing papers, missing parameters, missing list entries) must be filled by additional retrieval before delivery, never pushed to the next round; only user-side information gaps (school templates, quota numbers, advisor comments, raw data, attachments) may wait for the next round, and must be listed explicitly at the end of the delivery — what is asked and how much is missing. Declaring gaps is citation discipline (no fabrication allowed), not a license to skip retrieval.
- One-round full-deliverable baseline for artifact tasks (anti-shrinkage red line): when the user names an artifact (report / plan / survey / comparison table / application / outline) in the first round, that round must deliver the complete artifact — candidate cards, staged advancement, and convergence questions apply only to open consultations where no artifact was named; multi-round process discipline (stages, converge-first, next-round promises) never justifies delivering less or lowering completeness in the first round. Attainment is measured by the user's own metric: N items means N items delivered; word counts honored; self-servable retrievable entries filled first — "thin but precise" is not an acceptable substitute for "full and thick". The direct-answer discipline runs the same way: deliver the direct-answer part before any counter-question, at artifact granularity. Quota attainment must never be padded with degraded entries: when the constraint cannot be met, report the gap; never fill counts with non-compliant entries, bare entries, or downgraded ones — "met" means met on all of the user's criteria.
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.

