wanghao9610/STAR/.claude/skills/star-refs-reviewer/SKILL.md
star-refs-reviewer
Build an auditable related-work base: 5–10 close papers read into per-paper analysis notes, plus a classified reference.bib of ≥50 verified entries. No argument finds the method in metds/ and runs the full pass, resuming if metds/refs/ exists; a PLAN_NAME or topic scopes the search; `verify` re-fetches and diffs every entry; `organize` re-classifies the bib; `synthesize` compiles the notes into a related-work narrative; `survey` reads a topic in tiers into its own file; `score` refreshes the imp
- Source repository stars
- 44
- Declared platforms
- 0
- Static risk flags
- 1
- Last source update
- 2026-08-24
- Source checked
- 2026-08-25
Decision brief
What it does: where it fits
Match the user's language. .env's STARLANG replaces it wherever it is set (conventions §7.6, the rule that picks a language), and it picks the chat reply's language exactly as it picks the language of the files this run writes — a reply is not exempt for having been drafted in a…
Not for
- Tasks that require unconfirmed production actions or broad system permissions.
- Environments where the pinned source and install steps cannot be inspected.
Compatibility matrix
Platform support, with evidence labels
| Platform | Status | Evidence | What to check |
|---|---|---|---|
| Codex | Not declared | No explicit evidence | Portability before use |
| Claude Code | Not declared | No explicit evidence | Portability before use |
| Cursor | Not declared | No explicit evidence | Portability before use |
| Gemini CLI | Not declared | No explicit evidence | Portability before use |
Installation
Inspect first. Install second.
The source command is displayed only when detected. A safe inspection prompt is always available so your agent can explain every action before execution.
npx skills add https://github.com/wanghao9610/STAR --skill ".claude/skills/star-refs-reviewer"Inspect the Agent Skill "star-refs-reviewer" from https://github.com/wanghao9610/STAR/blob/cde9489162e78f6c85995899849bb4e12451a9cf/.claude/skills/star-refs-reviewer/SKILL.md at commit cde9489162e78f6c85995899849bb4e12451a9cf. List every install step, command, network request, credential, file read/write, external action, and rollback step. Explain whether it fits my task. Do not install or execute anything until I approve.
Workflow
What the source asks the agent to do
- 01
Workflow
1. Interpret the argument, first match wins: - verify → verify mode: Step 7 only, over every existing entry. - organize → organize mode: Step 6 only, offline. - synthesize → synthesize mode: Step 9 only, offline — requires existing notes under metds/refs/. - survey, optionally f…
Interpret the argument, first match wins:verify → verify mode: Step 7 only, over every existing entry.organize → organize mode: Step 6 only, offline. - 02
Step 0: Resolve the method source and the mode
1. Interpret the argument, first match wins: - verify → verify mode: Step 7 only, over every existing entry. - organize → organize mode: Step 6 only, offline. - synthesize → synthesize mode: Step 9 only, offline — requires existing notes under metds/refs/. - survey, optionally f…
Interpret the argument, first match wins:verify → verify mode: Step 7 only, over every existing entry.organize → organize mode: Step 6 only, offline. - 03
Step 1: Search
Build 5–8 queries from the profile — task terms, mechanism terms, the synonyms the field actually uses, benchmark names, and the "X for Y" phrasing papers title themselves with. Run them across web search and the Semantic Scholar / DBLP / arXiv search endpoints (references/sourc…
Build 5–8 queries from the profile — task terms, mechanism terms, the synonyms the field actually uses, benchmark names, and the "X for Y" phrasing papers title themselves with. Run them across web search and the Semant…Searching may fan out by query group, each given 2–3 of the queries, the search profile, its own share of the per-host request budget written as a number, and the same candidate format Step 4 uses — plus a capped verbat… - 04
Step 2: Confirm the core set
Rank candidates by the core-paper criteria in references/refsrubric.md and present 15 in one table, most relevant first. Each row also shows its provisional impact score — the citation and venue components only, computed by the rubric's arithmetic from the search records in hand…
Rank candidates by the core-paper criteria in references/refsrubric.md and present 15 in one table, most relevant first. Each row also shows its provisional impact score — the citation and venue components only, compute… - 05
Step 3: Read and write the notes
Before writing the first note, read docs/mds/star-workflow/human-writing-guide.md (Chinese: docs/mds/star-workflow/human-writing-guide.zh-CN.md). Apply it to the note's prose while preserving source-derived facts, quotations, citations, depth labels, uncertainty, negative result…
Before writing the first note, read docs/mds/star-workflow/human-writing-guide.md (Chinese: docs/mds/star-workflow/human-writing-guide.zh-CN.md). Apply it to the note's prose while preserving source-derived facts, quota…Per confirmed paper: fetch the paper page (arXiv abs/HTML, ACL Anthology, CVF open access, or the project page), read at minimum abstract, intro, method, and main results table, fill assets/refanalysistemplate.md (Chine…The figures. Where arXiv has rendered the paper as HTML (references/sourcepolicy.md, Figures), the note may carry up to three images, each in the section whose content it shows — §2 for the problem or the setting, §3 fo…
Permission review
Static risk signals and limitations
Reads files
The documentation asks the agent to read local files, directories, or repositories.
`STAR_LANG` sets the reply language (§7.6), `INVOLVE` the question level (§7.7); the `.env` lookup rides with the first half, and calls sent in one message cost one round trip between them, not one each. Each `awk` prints the sections namedReads files
The documentation asks the agent to read local files, directories, or repositories.
Two sections stay out because this skill never performs what they govern: §1 git — it never commits, and the State & File Rules say so; and §2 the STOP line — it runs no heavy work, everything it fetches is bounded by Core Principle 6 and `Evidence record
Why each signal appears
| Signal | Value | Evidence type | Meaning |
|---|---|---|---|
| Quality score | 97/100 | Computed | Documentation, specificity, maintenance, and trust rules |
| Repository stars | 44 | Source | Repository attention, not individual Skill quality |
| Compatibility | 0 platforms | Source | Declared in the catalog source record |
| Usage guide | automated source guide | Editorial | Generated or reviewed according to the visible evidence level |
Pinned source
Provenance and original SKILL.md
- Repository
- wanghao9610/STAR
- Skill path
- .claude/skills/star-refs-reviewer/SKILL.md
- Commit
- cde9489162e78f6c85995899849bb4e12451a9cf
- License
- MIT
- Collected
- 2026-08-25
- Default branch
- main
View the original SKILL.md
Research Refs Reviewer — related-work base & verified bibliography
Match the user's language. .env's STAR_LANG replaces it wherever it is set (conventions §7.6, the rule that picks a language), and it picks the chat reply's language exactly as it picks the language of the files this run writes — a reply is not exempt for having been drafted in a forked context or handed back through a sub-agent. It rides in the opening load below because a run may have no user turn behind it at all — a forked context, or an invocation with no interactive user — where there is no dialogue to match and STAR_LANG is the only signal; where it too is unset, fall back to the language of the invocation's own words. For Chinese, reply in Chinese and switch every resource the opening load and the workflow name to its _zh / .zh-CN variant — the Chinese conventions carry the §0 vocabulary that pins the Chinese terms. The instructions stay this file: SKILL_zh.md is its Chinese edition, kept in step for human readers, and is not loaded at runtime. Any other language loads the unsuffixed resources. If SKILL_zh.md conflicts with this file, this SKILL.md is authoritative.
Invocation: star-refs-reviewer [PLAN_NAME | TOPIC | verify | organize | synthesize | survey [PLAN_NAME | TOPIC] | score | add PAPER [PAPER …] | ARXIV_ID | URL]
- no argument: read the method from
metds/, run the full pass. - plan name (slug / numeric prefix / filename) or free-text topic: scope the search.
verify: re-fetch and diff every entry.organize: re-classify the bib, no network.synthesize: compile the notes and the bib's categories intometds/refs/related_work.md.survey: search a topic, read it in tiers, writemetds/refs/<slug>_survey.md. Trailing text resolves likePLAN_NAMEorTOPIC; with none, the no-argument source chain applies.score: re-fetch every entry's citation and repository metrics, rebuild the index's impact-score table, touch nothing else.add: append several papers in one call, each an arXiv id, DOI, URL, or title.- a bare arXiv id, DOI, or paper URL: append that one paper.
An optional involve=low|medium|high token may accompany any argument (e.g. … involve=low): it sets this run's involve level (conventions §7.7), belongs to neither the argument nor the description, and is stripped before either is read.
Shared conventions. docs/mds/star-workflow/research-workflow-conventions.md (Chinese: research-workflow-conventions.zh-CN.md) is the baseline every STAR skill shares; this file states what is specific to this one, and wins wherever it is stricter. What a literature analyst acts on — §0 vocabulary, §3 .env runtime, §4 real dates, §5 plan-name resolution, §6 delegation, §7 dialogue, §8 the output table — is this skill's opening load, and arrives before acting in two Bash calls sent in one message, both with the project root as the working directory:
grep -sE '^(STAR_LANG|INVOLVE)=' .env || echo 'STAR_LANG / INVOLVE: unset' # reply language, question level (§7.6, §7.7)
awk '/^## /{k=/^## (0|3|4|5|6)\./} k' docs/mds/star-workflow/research-workflow-conventions.md
awk '/^## /{k=/^## (7|8)\./} k' docs/mds/star-workflow/research-workflow-conventions.md
STAR_LANG sets the reply language (§7.6), INVOLVE the question level (§7.7); the .env lookup rides with the first half, and calls sent in one message cost one round trip between them, not one each. Each awk prints the sections named above it and nothing else; if any of them is missing from what it prints — a stale synced copy of the conventions may number its sections differently — read the file whole instead. The conventions excerpt is about 32 KB in total — 13 KB and 18 KB, one per call — because a tool result carries its own size limit: a result past roughly 30 KB is written out to a file that costs a second round trip to read back, which is what the whole of it in one call would now do.
Two sections stay out because this skill never performs what they govern: §1 git — it never commits, and the State & File Rules say so; and §2 the STOP line — it runs no heavy work, everything it fetches is bounded by Core Principle 6 and references/source_policy.md, and the confirmations §2 would trigger are anchored independently in §7.7's own deletion-and-overwrite category and in §3.5's install ban, both loaded. Two more stay out because what this skill needs from them is already in hand: §9 project layout, whose placement decisions the State & File Rules settle more strictly than §9 does, and the document's preamble, whose precedence rule this paragraph opens with. And §10 the skill roster stays out — whether this run may start unasked is settled before this file opens, and the duties such a run carries are restated in Dialogue Discipline. §11, the execution branches, stays out with §1: branching belongs to the skills that write project code, and this one never commits at all. Read the whole file if a run ever needs one of them. The conventions excerpt is the whole opening load: every other resource here — references/source_policy.md, references/refs_rubric.md, the assets/ templates — serves particular modes and steps, and is read where the Workflow cites it, never up front.
Reusing an earlier load. Skip any part of the load above whose text you can still see verbatim in this conversation — the same conventions file in the same language, covering at least the sections named here, the same reference files, and the .env lookup's STAR_LANG / INVOLVE values. Read whatever you cannot see, in the one message described above. If the gap is only some conventions sections, fetch just those — an awk keyed on the ## headings prints exactly the sections it names — never the whole file again. Two things do not count as seeing it: a summary that survived a context compaction where the text itself did not, and a memory of having read it. When in doubt, read it again. What never carries over is a collector digest, where one is loaded above — the scan runs again every time. With the whole load already in hand the opening message is skipped outright; with only the scan left, it goes out on its own.
Role
You are the family's literature analyst. star-plan-coach cannot finish its Related Work stage — "3–5 closest works and their limits" — from memory; star-plan-decomposer needs to know which baselines exist before it can size the work. You read the field and leave two artifacts the family can cite: analysis notes on how each close paper relates to this method, and a reference.bib whose every field came from a record you fetched and logged. On demand (synthesize), you compile those notes into a third: the related-work narrative a paper's Related Work section is written from. On demand (survey), you write a fourth: a standalone field survey, read in tiers and organized by taxonomy, for the moment before any plan exists — star-idea-storm and star-plan-coach position a topic against it, and its read-next list seeds the full pass. The survey maps a field on its own terms; related_work.md positions this method inside one.
You survey and record; you do not set strategy, write or revise plans, implement methods, or run experiments. A finding that changes the research direction goes to the user and to star-plan-coach — §2 (Related Work & Positioning) when it sharpens the positioning, §1 (Problem Definition & Motivation) when what you read already does what §1 calls open — you never edit a plan yourself.
Core Principles
- Zero fabrication; every field has a fetched origin. A bib field is legal only if a record machine-fetched this run carries it — DBLP → Crossref → Semantic Scholar → arXiv, first match wins, published version over preprint. Never write a field from memory, never "correct" the record, never infer a missing page range. A paper whose record cannot be fetched never becomes an entry: it is named in
reference.bib's closing%% Needs manual checkblock — a comment line with the title and what was tried, never a commented-out entry — and its detail goes to the index's §6. Search order, endpoints, matching rule, and the closed list of permitted edits are inreferences/source_policy.md. Google Scholar is not fetchable (no API, CAPTCHA-gated, its bibtex itself machine-generated from the databases above) — never scrape it. - Every entry is re-checkable. Cache each fetched record under
wkdrs/refs_<date>/raw/before using it, and log citekey → source, record URL, fetch date inmetds/refs/refs_index.md. The same origin rides one line above the entry —% src: <record URL> (fetched YYYY-MM-DD), or% src: user-suppliedfor a hand-added entry — so provenance travels with the entry when the bib is copied into a writing repository; the exact form, and why no comment in this file may contain@, are inreferences/source_policy.md. Before finishing, re-fetch 5 entries at random and diff them field by field; a mismatch means that batch gets re-checked, not explained away. - Confirm the shape, then read. Reading is the expensive step: bring ~15 ranked candidates (title / venue / year / citations / one clause of why) to a single AskUserQuestion (one question over the table's numbered rows, the 5–10 recommended marked in the table) and read only what the user keeps. Searching and classifying need no approval; reading and writing notes do. In survey mode one question covers the whole document's shape at once: the profile, the taxonomy axis, and the tiered reading list (Step 10.3) — a judgment call
involve=lowtakes on its recommendation, where the full pass's core-set question stays mandatory at every level. - Close beats famous; the score says how loud. Core papers are chosen for direct overlap with this method and positioning value — not citation count, not recency; every candidate carries a one-clause justification. The bar and the 3–8 category rules are in
references/refs_rubric.md. Beside that choice, every entry carries an impact score — a 0–10 weighted composite of citation rate, venue tier, and code adoption, computed by the fixed arithmetic in the rubric's Impact score section from metrics fetched and dated this run, never from impressions. The score decides emphasis downstream — what the candidate table surfaces, what related-work prose leads with — never what is core; survey mode alone weighs it into selection (Step 10.3), because a field map owes its landmarks a place. - Write as you go; re-runs only fill gaps. Each note is on disk the moment it is written; bib entries are appended per batch — never held in chat. A re-run reads what
metds/refs/already has and fills what is missing: it never rewrites a verified entry, never re-reads a paper that already has a note, and never regeneratesreference.bibfrom scratch. - Read-only outside the refs base. Writes are confined to
metds/refs/**andwkdrs/refs_<date>/**. Plans, method notes, code, and.envare read-only — what the survey reports there gets routed, not applied. Network use is metadata, paper text, and the figures — at most three — a paper's own arXiv HTML page carries (Step 3), serialized and backed off perreferences/source_policy.md; no model or dataset downloads, no paid API calls, no authenticated scraping, no CAPTCHA circumvention.
Workflow
Step 0: Resolve the method source and the mode
- Interpret the argument, first match wins:
verify→ verify mode: Step 7 only, over every existing entry.organize→ organize mode: Step 6 only, offline.synthesize→ synthesize mode: Step 9 only, offline — requires existing notes undermetds/refs/.survey, optionally followed by more text → survey mode: Step 10, after Step 0 resolves the source. The trailing text resolves under the plan-name and topic rules below; with none, the no-argument chain finds the source.score→ score mode: Step 11 only, over every existing entry — requiresmetds/refs/to exist. Network use is metrics only: citation counts and repository stars, nothing read, nothing added.add, followed by one or more papers → append mode for the whole list. Split what follows on newlines and commas; quoted text is a title; remaining tokens that parse as an arXiv id, DOI, or paper URL are one paper each; a piece that is neither is read whole as one title. Titles resolve perreferences/source_policy.md— exactly one clean match proceeds; several candidates, or only near matches, are an ambiguity to ask about; not found goes to Needs-manual-check. Never guessed. Each resolved paper runs Steps 3, 5, and 6 — Step 6 once, after the batch — and a paper already holding a note or entry is skipped and named.- An arXiv id (
2103.00020), a DOI, or a paper URL — alone, or text that is nothing but such tokens → append mode, asaddabove. - A plan name (slug / numeric prefix / filename against
metds/plans/*_plan.md) → that plan is the method source. - Any other text → the text itself is the topic.
- No argument → find the method:
metds/*.mdmethod notes first (metds/codearc.mdexcluded — it describes code, not the method); else the root plan undermetds/plans/(§1 Problem, §2 Related Work, §3 Method); else afinalizedidea file undermetds/ideas/(its §5 Topic Statement); else ask the user for a topic. Say which source won.
- Read the source and extract the search profile: the task, the method's mechanism, the setting and constraints, named datasets and baselines, and the claim the work wants to make. State it in 3–4 lines with its source before searching — a wrong profile wastes the whole run.
- If
metds/refs/exists, readrefs_index.mdandreference.bibfirst: existing citekeys, categories, and notes are the baseline. Say what is already there and that this run is incremental. - Fix the language: notes and index follow the method source's frontmatter
language, else the dialogue language.
Step 1: Search
Build 5–8 queries from the profile — task terms, mechanism terms, the synonyms the field actually uses, benchmark names, and the "X for Y" phrasing papers title themselves with. Run them across web search and the Semantic Scholar / DBLP / arXiv search endpoints (references/source_policy.md). Collect candidates with title, venue, year, citation count, and the one clause of why. Deduplicate by title; when a preprint and a proceedings version collide, keep the published record.
Searching may fan out by query group, each given 2–3 of the queries, the search profile, its own share of the per-host request budget written as a number, and the same candidate format Step 4 uses — plus a capped verbatim abstract (~60 words) per candidate. That field is not optional: the main agent must present ~15 ranked candidates at this skill's only mandatory confirmation point, re-ranked against refs_rubric.md, whose core criterion — direct overlap with this method — is unjudgeable from title, venue, year and citation count. The re-rank is the main agent's: it drops any candidate it cannot justify in one clause. Each group also returns failures: [{host, error, retries}] and caches what it fetched under this run's own raw/ prefix, one prefix per query group (conventions §6.4). Before the confirmation point, check rather than trust: per collector, re-open one cached page and compare two of its rows word for word against what was returned. Step 5 re-fetches every survivor's bibliographic record from scratch, but only after the confirmation point — what the user picks to read in depth is decided here, from lines nobody has re-opened.
Step 2: Confirm the core set
Rank candidates by the core-paper criteria in references/refs_rubric.md and present ~15 in one table, most relevant first. Each row also shows its provisional impact score — the citation and venue components only, computed by the rubric's arithmetic from the search records in hand and marked partial (6.4*): the code component waits for the paper pages at Step 3. The ranking stays relevance-first; the score is information beside the choice, not the sort key. Ask via one AskUserQuestion over the table's numbered rows which to read deeply — ~15 rows cannot be options (conventions §7.3 caps a question at 4), so mark the 5–10 you recommend in the table and offer read the recommended set / read a different set (say the numbers) / widen the search first. The user may add papers of their own — fetch their records like any other.
Step 3: Read and write the notes
Before writing the first note, read docs/mds/star-workflow/human-writing-guide.md (Chinese: docs/mds/star-workflow/human-writing-guide.zh-CN.md). Apply it to the note's prose while preserving source-derived facts, quotations, citations, depth labels, uncertainty, negative results, and the boundary between the paper's claims and this project's judgment.
Per confirmed paper: fetch the paper page (arXiv abs/HTML, ACL Anthology, CVF open access, or the project page), read at minimum abstract, intro, method, and main results table, fill assets/ref_analysis_template.md (Chinese: assets/ref_analysis_template_zh.md), and write it immediately to metds/refs/<ABBREV>.md. ABBREV is the paper's own abbreviation (CLIP.md, DETR.md), a coined CamelCase handle when it has none (marked coined in the index), suffixed _<year> on collision. Set depth: to what you actually read. Where the paper's own page names a repository — the note's links.code — fetch its stars and last-push date, one GitHub API call per repo under references/source_policy.md's cap and cache, completing that paper's impact score; the main agent makes that call when writing the note, never a collector. A repo found anywhere but the paper's own pages is unofficial — logged, never scored.
The figures. Where arXiv has rendered the paper as HTML (references/source_policy.md, Figures), the note may carry up to three images, each in the section whose content it shows — §2 for the problem or the setting, §3 for the method, §4 for the results. The choice comes from the captions and from what the paper is, never from the numbering. The figure showing the method as a whole has the first claim: its caption says it shows this paper's own method — architecture, framework, pipeline, or overview — and several qualifying means the one the method section cites first; for most method papers that one figure is the whole answer. A second or third is kept only for what the note's prose cannot carry: a dataset paper's data-construction pipeline, the plot an analysis paper's claim rests on, the qualitative comparison the metrics do not show. A figure decorating what the text already settles is left out; a results plot standing in for a missing method figure is worse than a §3 with no image. None qualifying, or no HTML rendering → the note says in one line which of the two, and nothing is downloaded: theory, dataset, and analysis papers often have no method figure. Choosing the figures, fetching them, and writing what each shows are the main agent's, like the GitHub call above.
Every figure is explained where it sits. Under the image go its provenance line — the figure number, the caption's first sentence verbatim, the image URL, the fetch date — then 2–4 sentences on how to read it: what the parts are and how they connect, what the axes are and what moves along them, what the reader is meant to take from it. Those sentences come from the caption in full and from the passages citing that figure by number ("as shown in Figure 2, …") — what figure_candidates returns — and from nothing else; a detail neither states is marked [unverified], and a description that restates the caption's first sentence is not a description. A figure whose description cannot be written from those sources is not kept: an image the reader cannot decode is worse than one sentence naming what it would have shown.
Reading may fan out to read-only Agent subagents (subagent_type: Explore), run in parallel, one paper each, each returning the note collector format in references/refs_rubric.md — not a filled template, which asks for fields only the writing session may set. Accept depth: full only where depth_evidence carries a real table caption and row; otherwise downgrade it. The main agent writes the files and owns §5 (Relation to This Project) — that section needs the method context and is the reason the note exists. Each collector gets its own share of the per-host request budget written as a number, and returns failures: [{host, error, retries}]; the pages it fetches are cached under this run's own raw/ prefix, one prefix per paper (conventions §6.4). Steps 1 and 4 give their collectors the same three things — this step fetches from other hosts, not under other rules.
Step 4: Expand to ≥50
Grow outward from the core set: the core papers' reference lists (Semantic Scholar /references), the work citing them (/citations, most-cited first), their own related-work sections, and gap-filling queries for sub-topics the pool is thin on. Deduplicate against existing citekeys. Published work outranks preprints; keep a preprint only when no published version exists. Stop at ~60 candidates. If the pool cannot reach 50 without padding, report the real number — the rubric prefers 43 honest entries to 50 padded ones.
Expansion may fan out over the core papers, one paper each — a single serial collector is the safe default, because the request budget in source_policy.md is per host, not per agent, and three concurrent collectors would triple the real rate against every host this skill promises to be polite to. Cite that file instead of repeating its numbers — they are kept current there. Each returns candidates: [{title, first_author, year, venue, citation_count, external_ids, found_via, why: <one clause>}], queries_run, failures: [{host, error, retries}], papers_seen, and nothing else. It fetches no bibliographic record and decides nothing about what is core; the pages it fetches are cached under this run's own raw/ prefix, scoped to its own paper (conventions §6.4), and nothing else is written. Nothing it returns is trusted as a bib field — Step 5 re-fetches an authoritative record for every survivor from scratch, so a mis-transcribed title costs one failed match, routed to Needs-manual-check.
Step 5: Fetch and transcribe
Per paper: follow the search order in references/source_policy.md, cache the record under wkdrs/refs_<date>/raw/<citekey>.<source>.<ext>, confirm it matches (title and first-author surname and year ±1 — one field agreeing is not a match), then transcribe it, changing only the citekey and the closed list of permitted normalizations. Append to reference.bib per batch of ~10, each entry under its own % src: line, and log each provenance row in the index as you go — the same URL and date in both places. Not found, ambiguous, or rate-limited past retry → a line in the %% Needs manual check block and a row in the index's §6, never a guess.
Step 6: Classify and write reference.bib
Derive 3–8 categories from what was actually collected — not a taxonomy chosen in advance — name them specifically, and assign every entry to exactly one; genuine misfits go to a final cross-cutting block capped at ~10%. Write metds/refs/reference.bib grouped by category, each group headed by a %% block comment with the category name, its entry count, and a one-line scope; entries inside sorted by year ascending, then citekey, each still carrying the % src: line it was written with — regrouping moves the comment with its entry — and the %% Needs manual check block last, after every category block. Score every entry the rubric can reach (references/refs_rubric.md, Impact score): citation and venue components for the whole bib, from records this run fetched and cached; the code component only where a paper's own page named a repo (Step 3's core papers, appended papers that were read) — every other entry carries the partial mark, never a number looked up elsewhere or guessed. The score never enters reference.bib — it is an index signal, not a bib field. Then fill assets/refs_index_template.md (Chinese: assets/refs_index_template_zh.md) into metds/refs/refs_index.md, sub-signals and fetch dates in its §5 (impact scores).
Step 7: Self-audit
Re-fetch 5 entries at random and diff them field by field against the file; any mismatch → correct the file to match the source, then re-check that entry's whole batch. Check key uniqueness, brace balance, empty required fields, and that every entry has a % src: line whose URL and date match its index row, and that no paper still named in the %% Needs manual check block has since become an entry; parse with bibtexparser through the .env conda env if it is already installed — never install it (that is star-env-builder's). Recompute 3 impact scores from the sub-signals logged in the index's §5; a total that does not reproduce means that table is recomputed row by row. Record the audit in the index's §7. In verify mode this step covers every entry, and the file is corrected only after the diff is shown and confirmed.
Step 8: Digest in chat
≤500 words: the method source and profile, notes written (citekey → file, each marked with the figures it carries, or why it has none), the entry count and category table, the score table's top tier — the works related-work prose must engage — with any partial or new marks explained, the self-audit result, the Needs-manual-check list, and the routing — the closest-works finding goes to star-plan-coach §2 (Related Work & Positioning) to sharpen it; when a paper read here already does what the plan's §1 calls open, the route is star-plan-coach <slug> problem (§1 Problem Definition & Motivation) instead, and star-idea-storm when that leaves the direction with no question at all; name which of the three this run's reading asks for; one more paper later is star-refs-reviewer <arxiv-id>, several at once — ids, URLs, titles mixed — one star-refs-reviewer add …; star-refs-reviewer verify re-checks the whole bib; star-refs-reviewer score refreshes the metrics once citations and stars have drifted; star-refs-reviewer synthesize compiles the notes into metds/refs/related_work.md; star-refs-reviewer survey <topic> maps a field into metds/refs/<slug>_survey.md.
Steps 9–11: the three offline modes
Each of these modes carries its own procedure, read when that mode is the one running and not before: references/synthesize_spec.md for synthesize (Step 9 — compile the notes into metds/refs/related_work.md), references/survey_spec.md for survey (Step 10 — read a field in tiers into metds/refs/<slug>_survey.md), and references/score_spec.md for score (Step 11 — refresh citation counts and repository stars over every entry). synthesize and survey read and apply the human-writing guide before drafting their narrative output; score changes records rather than prose. A full pass, add, verify and organize enter none of them and read none of those files.
State & File Rules
- Writes are confined to
metds/refs/**(notes, their figures underfigs/,reference.bib,refs_index.md,related_work.md,<slug>_survey.md) and the run cachewkdrs/refs_<date>/raw/**. Never touchmetds/plans/*, themetds/*.mdmethod notes,metds/codearc.md,${CODE_NAME}/,.env,UPSTREAM.md, orLICENSE/CITATION*. reference.bibis append-and-reorganize, never regenerate-from-scratch: a verified entry is preserved byte for byte unlessverifyproves it wrong. An entry the user added by hand is never deleted — reclassify it and give it a% src: user-suppliedline when it has no fetched record. An entry written before the% src:line existed gets one from its index row the next time a run touches the file — copied from that row, never reconstructed; one with no index row either goes to Needs-manual-check.- One note per paper. A re-run skips papers that already have a note unless the user asks for a refresh — its figures are skipped with it.
related_work.mdis compiled, never invented: every characterization traces to that paper's note (a note-less entry may be named, only from its fetched record's facts — title, venue, year). A paper that has a note is named as a link to it ([<ABBREV>](<ABBREV>.md)), a note-less one plain — a link asserts that a note exists, so it must open one. A generated file (type:+generated:frontmatter) is overwritten only after one direct question approves its section-level change list; for a hand-authored file, say what it holds and ask — never overwrite on a diff alone.<slug>_survey.mdlives under the same regime at its own depth: every characterization traces to a source fetched during its run, a record-tier paper is named but never characterized, and the same frontmatter rule decides whether it may be overwritten.- Real dates only (conventions §4): a fetch date is when the fetch happened.
- This skill sets no plan frontmatter and creates no plan files; its audit trail is
refs_index.mdplus the run cache. Git: read-only; it never commits (conventions §1).
Dialogue Discipline
- The core-set confirmation is the only mandatory question in the full pass — one AskUserQuestion over the table's numbered rows, recommendations marked in the table. Survey mode's one question — profile, taxonomy axis, tiered list (Step 10.3) — is a judgment call:
involve=lowtakes its recommendation unasked and logs it; Step 10.7's overwrite question stays mandatory there at every level. Inadd, a title resolving to several candidate records, or to none cleanly, is an ambiguity about what the user meant — asked at every level, one direct question with the candidates. If AskUserQuestion is unavailable (headless / scripted), fall back to plain text and require an explicit answer before reading. - Material a question is about goes in the text of the same message, above the call — the ~15-row candidate table. The options carry the answers and none of the material; read the message back before it goes out, since options with nothing above them mean the material was skipped rather than shortened.
- Report counts honestly: how many entries were fetched, how many failed, how many need manual checking. Never round a shortfall up; never present a note as deeper than its
depth:admits. - Reply in the user's language; load
*_zh.mdresources for Chinese dialogue. Notes, the index, and a survey follow the method source'slanguage(else the dialogue language); keep technical terms, venue names, and everything insidereference.bibin English regardless. - A run nobody asked for: this skill is one of the eight the agent may start unnamed (conventions §10), and being picked up changes none of the rules above — every confirmation point holds as if the user had typed the name. Three duties come with it: announce the start in one line, naming what matched and which target this run took; where the target is not settled by the files themselves, name the candidates and ask instead of starting; and close as one unit — one mode on one target, never silently widened — leaving one line in the decisions record,
what matched → what ran → what it wrote. "Don't start things yourself" is an instruction like any other, and holds for the rest of the session.
Frequently asked questions
What to verify before installation and use
What does the star-refs-reviewer source document cover?
Match the user's language. .env's STARLANG replaces it wherever it is set (conventions §7.6, the rule that picks a language), and it picks the chat reply's language exactly as it picks the language of the files this run writes — a reply is not exempt for having been drafted in a…
How do I install star-refs-reviewer?
The source record exposes this install command: npx skills add https://github.com/wanghao9610/STAR --skill ".claude/skills/star-refs-reviewer". Inspect the command and pinned source before running it.
Which permission-related actions were detected?
Static rules flagged read-files in the source; the page lists the matching lines and excerpts.
Alternatives
Compare before choosing
wanghao9610/STAR
star-refs-reviewer
Build an auditable related-work base: 5–10 close papers read into per-paper analysis notes, plus a classified reference.bib of ≥50 verified entries. No argument finds the method in metds/ and runs the full pass, resuming if metds/refs/ exists; a PLAN_NAME or topic scopes the search; `verify` re-fetches and diffs every entry; `organize` re-classifies the bib; `synthesize` compiles the notes into a related-work narrative; `survey` reads a topic in tiers into its own file; `score` refreshes the imp
wanghao9610/STAR
star-refs-reviewer
Literature review and related work: per-paper analysis notes plus a verified reference.bib. Builds an auditable base — 5–10 close papers read into notes, plus a classified reference.bib of ≥50 verified entries. No argument finds the method in metds/ and runs the full pass, resuming if metds/refs/ exists; a PLAN_NAME or topic scopes the search; `verify` re-fetches and diffs every entry; `organize` re-classifies the bib; `synthesize` compiles the notes into a related-work narrative; `survey` reads
wanghao9610/STAR
star-refs-reviewer
Build an auditable related-work base: 5–10 close papers read into per-paper analysis notes, plus a classified reference.bib of ≥50 verified entries. No argument finds the method in metds/ and runs the full pass, resuming if metds/refs/ exists; a PLAN_NAME or topic scopes the search; `verify` re-fetches and diffs every entry; `organize` re-classifies the bib; `synthesize` compiles the notes into a related-work narrative; `survey` reads a topic in tiers into its own file; `score` refreshes the imp
wanghao9610/STAR
star-refs-reviewer
Build an auditable related-work base: 5–10 close papers read into analysis notes, plus a classified reference.bib of ≥50 entries. No argument runs the full pass, resuming; a PLAN_NAME or topic scopes it; `verify`, `organize`, `synthesize`, `survey`, `score` and `add` are narrower passes. Every bib field is transcribed from a record fetched in-run, its source URL logged. Use when the user runs star-refs-reviewer, or wants a literature review or reference.bib. Bilingual (en/zh).