dongzhigang13305312738-art/paper-skills / bib-search-citation
bib-search-citation
VerifiedSearch and cite from local BibTeX/BibLaTeX .bib libraries, including Zotero exports. Use to find, filter, preview, export, or generate LaTeX/Typst citation snippets by topic, author, year, venue, DOI, arXiv ID, keywords, abstract, fields, recency, or claim support. Do not use for manuscript writing or polishing.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.0 KB |
| agents/openai.yaml | config | 400 B |
| evals/evals.json | config | 4.4 KB |
| evals/trigger_eval.json | config | 2.9 KB |
| examples/compact-query.md | markdown | 830 B |
| examples/preview-summary.md | markdown | 717 B |
| examples/raw-bib-export.md | markdown | 666 B |
| references/limitations-and-errors.md | markdown | 2.6 KB |
| references/query-syntax.md | markdown | 8.9 KB |
| references/search-planning.md | markdown | 1.3 KB |
| scripts/preview_bib_search.py | script | 8.3 KB |
| scripts/search_bib.py | script | 48.7 KB |
| tests/fixtures/biblatex.bib | other | 464 B |
| tests/fixtures/broken.bib | other | 421 B |
| tests/fixtures/library.bib | other | 1.6 KB |
| tests/fixtures/phantom.bib | other | 514 B |
| tests/fixtures/preview_input.json | config | 1.5 KB |
| tests/fixtures/quote_trap.bib | other | 438 B |
| tests/test_bib_search.py | script | 21.0 KB |
references/query-syntax.md
View on GitHub# Query Syntax Guide
This reference helps map literature requests into a search spec for `scripts/search_bib.py`.
## Two supported input styles
The script supports both of these styles:
1. a JSON search spec
2. a compact query expression
Use the compact form when the user naturally writes something like:
```text
time series forecasting mamba author:Cheng year>=2024 has:code type:article,misc cite:both
```
Use the JSON form when the workflow already has a structured spec or when many filters need to be explicit.
## JSON search spec shape
```json
{
"query": "mamba time series forecasting",
"filters": {
"year_min": 2024,
"year_max": 2026,
"author_contains": ["Cheng"],
"type_in": ["article", "misc"],
"has": ["code", "abstract"],
"exclude_has": ["pdf"],
"field_contains": {
"annotation": ["CodeAvailable"],
"keywords": ["forecasting"]
}
},
"sort": "relevance",
"limit": 5,
"return_fields": [
"key",
"title",
"shorttitle",
"author",
"year",
"venue",
"doi",
"eprint",
"keywords",
"annotation",
"abstract"
],
"include_raw_bib": true,
"citation_mode": "both"
}
```
## Compact query language
### Core syntax
- plain words remain the theme query
- `author:cheng` -> author contains `cheng`
- `year>=2024` -> year minimum is 2024
- `year<=2025` -> year maximum is 2025
- `year:2024` -> exact year 2024
- `year:2023,2024` -> year is 2023 or 2024
- `type:article,misc` -> entry type in article or misc
- `-type:misc` -> exclude misc entries
- `has:code,doi` -> require both code and doi
- `-has:pdf` -> exclude entries that appear to include a PDF
- `annotation:CodeAvailable` -> annotation contains `CodeAvailable`
- `keywords:mamba` -> keywords contains `mamba`
- `sort:year_desc` -> newest first
- `limit:10` -> return 10 results
- `fields:key,title,year,doi` -> restrict returned fields
- `cite:latex` / `cite:typst` / `cite:both`
- `raw:true` -> include raw BibTeX
- `recent:3` -> set the recency window (years) for the additive `meta.recency` report; also available as the `--recent-window` flag
- `claim:"low-latency forecasting"` -> attach a per-result `claim_support` block (lexical overlap only); also available as the `--claim` flag (preferred for claims with spaces)
### Notes
- Multiple compact filters can be mixed freely.
- Tokens that do not match the compact syntax stay in the free-text theme query.
- The parser also accepts compact syntax inside `spec.query` when a JSON spec is used.
- Generic field filters work for many fields, including `title`, `shorttitle`, `annotation`, `keywords`, `abstract`, `file`, `copyright`, `doi`, and `eprint`.
- Negated generic field filters are written like `-annotation:survey`.
- Any `word:word` token is treated as a generic field filter, so a misspelled field name (`tilte:...`) matches nothing; `meta.parse_warnings` flags a filter field that is absent from every entry.
- If you want a compact human-readable summary after the search, pipe the JSON into `scripts/preview_bib_search.py` instead of changing the query syntax.
## Recency report and claim binding (additive)
Both features are additive and never filter or reorder results.
- **Recency** is always reported under `meta.recency`: `window_years`, `recent_threshold`
(computed from the current calendar year, so it stays correct over time),
`with_year`, `recent_count`, `recent_share`, and a `note` that warns when fewer than
80% of returned results fall inside the window. Tune the window with `recent:N` or
`--recent-window N` (default 3).
- **Claim binding** runs only when a claim is supplied via `--claim "..."` (preferred) or
`claim:"..."`. Each result then gains a `claim_support` block with `relevance`,
`matched_fields`, `shared_terms`, and a `provenance` note. This is lexical overlap, **not**
proof of support — keep it as a verification hand-off, never as evidence the paper backs
the claim.
JSON spec form:
```json
{
"query": "low-latency time-series forecasting",
"recent_window": 3,
"claim": "our sparse attention reduces inference latency"
}
```
## Natural-language mapping examples
### Theme search
User request:
> Find papers on long-term time-series forecasting that use Mamba.
Compact form:
```text
long-term time series forecasting mamba cite:both
```
Suggested JSON spec:
```json
{
"query": "long-term time series forecasting mamba",
"sort": "relevance",
"limit": 5,
"citation_mode": "both"
}
```
### Theme search with explicit filters
User request:
> Find 2024 or later Cheng papers on Mamba for time-series forecasting, preferably with code.
Compact form:
```text
mamba time series forecasting author:Cheng year>=2024 has:code cite:both limit:8
```
Suggested JSON spec:
```json
{
"query": "mamba time series forecasting",
"filters": {
"year_min": 2024,
"author_contains": ["Cheng"],
"has": ["code"]
},
"sort": "relevance",
"limit": 8,
"citation_mode": "both"
}
```
### Field-specific filter
User request:
> Show entries whose annotation contains CodeAvailable and whose abstract mentions photovoltaic.
Compact form:
```text
photovoltaic annotation:CodeAvailable raw:true cite:none
```
Suggested JSON spec:
```json
{
"query": "photovoltaic",
"filters": {
"field_contains": {
"annotation": ["CodeAvailable"],
"abstract": ["photovoltaic"]
}
},
"include_raw_bib": true,
"citation_mode": "none"
}
```
### Negation and exclusion
User request:
> Find recent transformer papers for time-series forecasting, but exclude arXiv-only misc entries and exclude entries without DOI.
Compact form:
```text
transformer time series forecasting year>=2022 -type:misc has:doi
```
Suggested JSON spec:
```json
{
"query": "transformer time series forecasting",
"filters": {
"year_min": 2022,
"exclude_type_in": ["misc"],
"has": ["doi"]
},
"sort": "relevance"
}
```
### Bibliographic export check
User request:
> Return the original BibTeX entry and both LaTeX and Typst citation forms for the best match to TimeMachine.
Compact form:
```text
TimeMachine raw:true cite:both limit:1
```
Suggested JSON spec:
```json
{
"query": "TimeMachine",
"sort": "relevance",
"limit": 1,
"include_raw_bib": true,
"citation_mode": "both"
}
```
## Sorting guidance
- `relevance`: best default for topic-based discovery
- `year_desc`: useful for newest-first scans
- `year_asc`: useful for historical development views
- `title`: useful when reviewing a narrow candidate set
## Edge cases
### Colons in free text
A compact token shaped like `name:value` is interpreted as a field filter when
`name` starts with an ASCII letter or underscore. This includes unfamiliar names:
`genotype:phenotype` becomes a filter on the field `genotype`, so the token is
removed from the free-text query and does not contribute to relevance scoring.
When that field is absent from every entry, `meta.parse_warnings` reports an
`unknown_field_filter` warning.
Tokens whose prefix starts with a digit do not match the field-filter syntax.
For example, `10:30` remains free text. If a letter-prefixed colon token was meant
as free text, replace the colon with a space (`genotype phenotype`). The relevance
tokenizer already treats punctuation as a separator, so this preserves the terms
used for scoring. Real fields such as `note:` and `title:` always remain filters
and do not warn when the field exists in the library.
### Filter-only query (no topic words)
When the user only wants to filter without a topic search, all matching entries receive a score of zero and the sort mode determines the order. Example:
```text
author:Cheng year>=2024 type:article sort:year_desc
```
This returns all articles by Cheng from 2024 onward, sorted newest first, without any relevance ranking.
### Empty results guidance
If no entries match the query, try broadening filters step by step:
1. Remove `has:` constraints — `has:code` and `has:pdf` are the most restrictive
2. Widen or drop the year range
3. Use fewer topic keywords or try synonyms
4. Check author name spelling. The author filter is a case-insensitive,
accent-folded substring match, so `author:Muller` matches `M{\"u}ller` and a
partial name like `author:chen` matches both `Chen` and `Cheng`. That breadth
is convenient for recovery but also a false-positive risk: confirm the author
identity before citing rather than trusting a substring hit.
## Known limitations
- Author matching does not normalise name order or `von`/particle handling, so
`author:"Jane Doe"` will not match a `{Doe, Jane}` field; search by surname.
- `matched_entries` counts structured-filter matches only; it does not report how
many entries the free-text relevance threshold dropped.
- CJK queries match best as a contiguous substring (`时间序列`); space-separated
CJK terms may not all match.
- Multi-file libraries are not merged — run the script once per `.bib` file.
- Years are detected in the 1500–2099 range; entries without a parseable year are
excluded by any year filter.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |