citation-topics 0.1.0__tar.gz

citation_topics-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+# Add here any generated outputs or data files that hold personal data (e.g. downloaded pages)
+# Never commit credentials
+.env
+.pypirc
+*apikey*

citation_topics-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and versions follow [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-15
+
+### Added
+- `run`: direct-citation network of a JSON or JSON Lines list of works, Leiden topics (igraph) and areas
+  (leidenalg, best of several seeds), second and third topics of every work; `works.jsonl.gz`, `topics.json`,
+  `areas.json`, `meta.json`.
+- `describe`: dossier of every topic and area from the optional fields.
+- `names`, `compare` (fates and names carried over), `agreement` (NMI/ARI, medoid), `export` (VOSviewer, CSV).
+- Claude skills `topics-run`, `topic-namer`, `topics-compare` and the agent `topic-namer` (`skills install`).
+
+[Unreleased]: https://github.com/restrepo/citation-topics/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/restrepo/citation-topics/releases/tag/v0.1.0

citation_topics-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Diego Restrepo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

citation_topics-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.5
+Name: citation-topics
+Version: 0.1.0
+Summary: Research topics and areas from the citation links of any list of works, with Leiden clustering as CWTS does for OpenAlex.
+Project-URL: Homepage, https://github.com/restrepo/citation-topics
+Project-URL: Repository, https://github.com/restrepo/citation-topics
+Project-URL: Issues, https://github.com/restrepo/citation-topics/issues
+Project-URL: Changelog, https://github.com/restrepo/citation-topics/blob/main/CHANGELOG.md
+Author-email: Diego Restrepo <restrepo@udea.edu.co>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bibliometrics,citation network,community detection,leiden,scientometrics,topics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: igraph>=0.11
+Requires-Dist: leidenalg>=0.10
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff==0.17.3; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# citation-topics
+
+[![CI](https://github.com/restrepo/citation-topics/actions/workflows/ci.yml/badge.svg)](https://github.com/restrepo/citation-topics/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/citation-topics.svg)](https://pypi.org/project/citation-topics/)
+[![Python](https://img.shields.io/pypi/pyversions/citation-topics.svg)](https://pypi.org/project/citation-topics/)
+
+Research topics and broad areas for any list of works (papers, theses, projects, patents) from their citation
+links, with Leiden clustering of the direct-citation network as CWTS does for the OpenAlex topics. It also gives
+each work a second and a third topic, describes every topic from whatever the input carries (titles, abstracts,
+keywords, journals, categories, countries), and ships Claude skills and an agent that name the topics.
+
+It was extracted from [restrepo/inspireauth10](https://github.com/restrepo/inspireauth10), where it groups 1.9
+million INSPIRE-HEP papers into 304 topics and 6 areas
+([how the topics are made](https://restrepo.github.io/inspireauth10/leiden.html)).
+
+## Install
+
+```bash
+pip install citation-topics
+citation-topics --help
+```
+
+## Input
+
+A JSON array or JSON Lines file (optionally gzipped), one object per work:
+
+```json
+{"id": "W1", "references": ["W7", "W9"], "year": 2019, "title": "...", "abstract": "...",
+ "keywords": ["..."], "journal": "...", "categories": ["..."], "countries": ["..."],
+ "authors": ["..."], "citations": 41, "url": "https://..."}
+```
+
+- `id` (unique; strings or integers, compared as strings) and `references` (ids of other works) are required.
+  References to ids outside the list and self-citations are ignored and counted.
+- Every other field is optional. Other names are read with `--id-field`, `--refs-field` and
+  `--map NAME=FIELD` (for example `--map year=publication_year`).
+
+| Optional field | Adds |
+|---|---|
+| `year` | years of each topic, time windows (`--from-year`, `--to-year`), comparisons between epochs |
+| `title`, `abstract`, `keywords`, `journal`, `categories` | the description of each topic (`describe`), hence its name |
+| `citations` | most cited works by that count (otherwise by citations inside the list) |
+| `countries` | countries of each topic in the description |
+| `authors`, `url` | counted in `meta.json`; `url` is copied to the most cited works of the description |
+
+## Commands
+
+```bash
+citation-topics run works.jsonl.gz out/            # network, topics, areas, second and third topics
+citation-topics describe works.jsonl.gz out/       # out/dossier.json: what each topic is about
+citation-topics names out/ names.json              # put names into topics.json and areas.json
+citation-topics export out/                        # VOSviewer JSON and map/network files, CSVs
+citation-topics agreement out_s1/ out_s2/ ...      # NMI/ARI between seeds, and the medoid to keep
+citation-topics compare old/ new/ cmp/             # where earlier topics went; names carried over
+citation-topics skills install                     # Claude skills and the topic-namer agent into ./.claude
+```
+
+`run` options and defaults (those of the INSPIRE run): `--resolution 16` (higher = more, smaller topics),
+`--min-size 100` (smaller topics are merged into the topic they share the most links with), `--passes 20`
+(stops early when the quality stops rising), `--seed 1`, `--area-resolution 0.3`, `--area-seeds 50` (the best
+of that many runs). Tune them for other lists; the skill `topics-run` explains how.
+
+## Method
+
+1. **Network**: one node per work, an edge for each reference to another work of the list; undirected, each
+   pair of works once.
+2. **Topics**: Leiden maximizing modularity with a resolution parameter (the RB configuration model), with
+   igraph's `community_leiden`, pass after pass until the quality stops rising. Works with no link stay
+   unassigned; topics under `--min-size` are merged into their most linked neighbour; topics are numbered by
+   size.
+3. **Areas**: Leiden (leidenalg) on the graph of topics weighted by the links between them, with the links
+   inside each topic as self-loops, the best of `--area-seeds` runs. Every topic is in one area.
+4. **Second and third topics**: a work's links are counted by the topic at the other end; the second and third
+   topics are the most linked other topics, scored as links to them / links to the main topic, capped at 1.
+   Works the clustering left out take as main topic the one they link to most (`inferred`).
+5. **Description** (`describe`): per topic, its distinctive terms (shares in the topic against the rest of the
+   list), journals, categories, keywords, countries, years, linked topics and most cited works.
+6. **Names**: written by Claude from the description (skill `topic-namer`), never by the package. `compare`
+   carries names over from an earlier run: a topic sharing 60% of its works both ways with an earlier one keeps
+   its name.
+
+The same input, parameters and versions of igraph and leidenalg give the same topics; `meta.json` records them
+with the MD5 of the input.
+
+**Checked against inspireauth10.** On its 1,872,221 INSPIRE papers (44 million citation links) with the
+defaults, `run` gives the same network, the same 304 topics and 6 areas, the same Leiden quality and the same
+second and third topics as inspireauth10's own scripts, array for array (igraph 1.0.0, leidenalg 0.12.0, numpy
+2.5.4, Python 3.13). It took 45 minutes and more than 4 GB of memory; `describe` with titles, keywords,
+journals, categories and countries took 10 minutes and 4.4 GB.
+
+## Output
+
+| File | Content |
+|---|---|
+| `works.jsonl.gz` | per work: `id`, `topic`, `area` (null if none), `topics` (three, with `score` and `links`), `n_links`, `inferred` |
+| `topics.json` | per topic: area, name, works, links inside and out, `share_inside`, years, most cited works |
+| `areas.json` | per area: name, works, topics, links, `share_inside` |
+| `meta.json` | parameters, versions, input MD5, network counts, optional fields present, quality |
+| `dossier.json` | description of each topic and area (`describe`) |
+| `topics_vosviewer.json`, `topics_map.txt`, `topics_network.txt` | graph of topics for VOSviewer (`export`) |
+| `topics.csv`, `works_topics.csv.gz` | the same as tables (`export`) |
+| `network.npz`, `clusters.npz` | arrays reused by the other commands |
+
+## Claude skills
+
+`citation-topics skills install` copies into `./.claude` (or `~/.claude` with `--user`):
+
+- `topics-run`: checks the input, chooses the parameters, runs, describes and exports, and explains the result;
+- `topic-namer`: names topics and areas from `dossier.json` and applies them, after carrying over earlier names;
+- `topics-compare`: seeds (which run to keep) and earlier runs or time windows (fates, flows, names);
+- the agent `topic-namer`, which names a batch of topics when the skill hands it one.
+
+In Claude Desktop or Claude Code, ask for topics of a list of works and the skills take it from there.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+ruff check . && ruff format --check .
+```
+
+Releases are published to PyPI from GitHub Actions when a `v*` tag is pushed; see [PUBLISHING.md](PUBLISHING.md)
+and [CHANGELOG.md](CHANGELOG.md).

citation_topics-0.1.0/README.md

@@ -0,0 +1,124 @@
+# citation-topics
+
+[![CI](https://github.com/restrepo/citation-topics/actions/workflows/ci.yml/badge.svg)](https://github.com/restrepo/citation-topics/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/citation-topics.svg)](https://pypi.org/project/citation-topics/)
+[![Python](https://img.shields.io/pypi/pyversions/citation-topics.svg)](https://pypi.org/project/citation-topics/)
+
+Research topics and broad areas for any list of works (papers, theses, projects, patents) from their citation
+links, with Leiden clustering of the direct-citation network as CWTS does for the OpenAlex topics. It also gives
+each work a second and a third topic, describes every topic from whatever the input carries (titles, abstracts,
+keywords, journals, categories, countries), and ships Claude skills and an agent that name the topics.
+
+It was extracted from [restrepo/inspireauth10](https://github.com/restrepo/inspireauth10), where it groups 1.9
+million INSPIRE-HEP papers into 304 topics and 6 areas
+([how the topics are made](https://restrepo.github.io/inspireauth10/leiden.html)).
+
+## Install
+
+```bash
+pip install citation-topics
+citation-topics --help
+```
+
+## Input
+
+A JSON array or JSON Lines file (optionally gzipped), one object per work:
+
+```json
+{"id": "W1", "references": ["W7", "W9"], "year": 2019, "title": "...", "abstract": "...",
+ "keywords": ["..."], "journal": "...", "categories": ["..."], "countries": ["..."],
+ "authors": ["..."], "citations": 41, "url": "https://..."}
+```
+
+- `id` (unique; strings or integers, compared as strings) and `references` (ids of other works) are required.
+  References to ids outside the list and self-citations are ignored and counted.
+- Every other field is optional. Other names are read with `--id-field`, `--refs-field` and
+  `--map NAME=FIELD` (for example `--map year=publication_year`).
+
+| Optional field | Adds |
+|---|---|
+| `year` | years of each topic, time windows (`--from-year`, `--to-year`), comparisons between epochs |
+| `title`, `abstract`, `keywords`, `journal`, `categories` | the description of each topic (`describe`), hence its name |
+| `citations` | most cited works by that count (otherwise by citations inside the list) |
+| `countries` | countries of each topic in the description |
+| `authors`, `url` | counted in `meta.json`; `url` is copied to the most cited works of the description |
+
+## Commands
+
+```bash
+citation-topics run works.jsonl.gz out/            # network, topics, areas, second and third topics
+citation-topics describe works.jsonl.gz out/       # out/dossier.json: what each topic is about
+citation-topics names out/ names.json              # put names into topics.json and areas.json
+citation-topics export out/                        # VOSviewer JSON and map/network files, CSVs
+citation-topics agreement out_s1/ out_s2/ ...      # NMI/ARI between seeds, and the medoid to keep
+citation-topics compare old/ new/ cmp/             # where earlier topics went; names carried over
+citation-topics skills install                     # Claude skills and the topic-namer agent into ./.claude
+```
+
+`run` options and defaults (those of the INSPIRE run): `--resolution 16` (higher = more, smaller topics),
+`--min-size 100` (smaller topics are merged into the topic they share the most links with), `--passes 20`
+(stops early when the quality stops rising), `--seed 1`, `--area-resolution 0.3`, `--area-seeds 50` (the best
+of that many runs). Tune them for other lists; the skill `topics-run` explains how.
+
+## Method
+
+1. **Network**: one node per work, an edge for each reference to another work of the list; undirected, each
+   pair of works once.
+2. **Topics**: Leiden maximizing modularity with a resolution parameter (the RB configuration model), with
+   igraph's `community_leiden`, pass after pass until the quality stops rising. Works with no link stay
+   unassigned; topics under `--min-size` are merged into their most linked neighbour; topics are numbered by
+   size.
+3. **Areas**: Leiden (leidenalg) on the graph of topics weighted by the links between them, with the links
+   inside each topic as self-loops, the best of `--area-seeds` runs. Every topic is in one area.
+4. **Second and third topics**: a work's links are counted by the topic at the other end; the second and third
+   topics are the most linked other topics, scored as links to them / links to the main topic, capped at 1.
+   Works the clustering left out take as main topic the one they link to most (`inferred`).
+5. **Description** (`describe`): per topic, its distinctive terms (shares in the topic against the rest of the
+   list), journals, categories, keywords, countries, years, linked topics and most cited works.
+6. **Names**: written by Claude from the description (skill `topic-namer`), never by the package. `compare`
+   carries names over from an earlier run: a topic sharing 60% of its works both ways with an earlier one keeps
+   its name.
+
+The same input, parameters and versions of igraph and leidenalg give the same topics; `meta.json` records them
+with the MD5 of the input.
+
+**Checked against inspireauth10.** On its 1,872,221 INSPIRE papers (44 million citation links) with the
+defaults, `run` gives the same network, the same 304 topics and 6 areas, the same Leiden quality and the same
+second and third topics as inspireauth10's own scripts, array for array (igraph 1.0.0, leidenalg 0.12.0, numpy
+2.5.4, Python 3.13). It took 45 minutes and more than 4 GB of memory; `describe` with titles, keywords,
+journals, categories and countries took 10 minutes and 4.4 GB.
+
+## Output
+
+| File | Content |
+|---|---|
+| `works.jsonl.gz` | per work: `id`, `topic`, `area` (null if none), `topics` (three, with `score` and `links`), `n_links`, `inferred` |
+| `topics.json` | per topic: area, name, works, links inside and out, `share_inside`, years, most cited works |
+| `areas.json` | per area: name, works, topics, links, `share_inside` |
+| `meta.json` | parameters, versions, input MD5, network counts, optional fields present, quality |
+| `dossier.json` | description of each topic and area (`describe`) |
+| `topics_vosviewer.json`, `topics_map.txt`, `topics_network.txt` | graph of topics for VOSviewer (`export`) |
+| `topics.csv`, `works_topics.csv.gz` | the same as tables (`export`) |
+| `network.npz`, `clusters.npz` | arrays reused by the other commands |
+
+## Claude skills
+
+`citation-topics skills install` copies into `./.claude` (or `~/.claude` with `--user`):
+
+- `topics-run`: checks the input, chooses the parameters, runs, describes and exports, and explains the result;
+- `topic-namer`: names topics and areas from `dossier.json` and applies them, after carrying over earlier names;
+- `topics-compare`: seeds (which run to keep) and earlier runs or time windows (fates, flows, names);
+- the agent `topic-namer`, which names a batch of topics when the skill hands it one.
+
+In Claude Desktop or Claude Code, ask for topics of a list of works and the skills take it from there.
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+ruff check . && ruff format --check .
+```
+
+Releases are published to PyPI from GitHub Actions when a `v*` tag is pushed; see [PUBLISHING.md](PUBLISHING.md)
+and [CHANGELOG.md](CHANGELOG.md).

citation_topics-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[build-system]
+requires = ["hatchling>=1.24", "hatch-vcs>=0.4"]
+build-backend = "hatchling.build"
+
+[project]
+name = "citation-topics"
+dynamic = ["version"]
+description = "Research topics and areas from the citation links of any list of works, with Leiden clustering as CWTS does for OpenAlex."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+authors = [{ name = "Diego Restrepo", email = "restrepo@udea.edu.co" }]
+keywords = ["bibliometrics", "citation network", "leiden", "community detection", "topics", "scientometrics"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Typing :: Typed",
+]
+dependencies = ["numpy>=1.24", "igraph>=0.11", "leidenalg>=0.10"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-cov>=5", "ruff==0.17.3", "build>=1.2", "twine>=5"]
+
+[project.scripts]
+citation-topics = "citation_topics.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/restrepo/citation-topics"
+Repository = "https://github.com/restrepo/citation-topics"
+Issues = "https://github.com/restrepo/citation-topics/issues"
+Changelog = "https://github.com/restrepo/citation-topics/blob/main/CHANGELOG.md"
+
+# Version from the git tag (v0.1.0 -> 0.1.0); commits after a tag get 0.1.1.devN
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.version.raw-options]
+local_scheme = "no-local-version"   # PyPI and TestPyPI reject local versions (+g1234abc)
+
+[tool.hatch.build.targets.sdist]
+include = ["src/", "tests/", "README.md", "CHANGELOG.md", "LICENSE"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/citation_topics"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+
+[tool.coverage.run]
+source = ["citation_topics"]
+branch = true
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]
+ignore = ["B905"]  # zip() over arrays of equal length by construction

citation_topics-0.1.0/src/citation_topics/__init__.py

@@ -0,0 +1,11 @@
+"""Research topics and areas from the citation links of any list of works, with Leiden clustering as CWTS does
+for the OpenAlex topics."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("citation-topics")
+except PackageNotFoundError:  # running from a source tree that was never installed
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

citation_topics-0.1.0/src/citation_topics/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

citation_topics-0.1.0/src/citation_topics/claude/agents/topic-namer.md

@@ -0,0 +1,19 @@
+---
+name: topic-namer
+description: Names a batch of citation-topics topics or areas from OUT/dossier.json and writes them to a names JSON file. Give it the dossier path, the topic (or area) numbers, the output file, and the names already used elsewhere so it avoids duplicates.
+tools: Read, Write, Bash
+---
+
+You name research topics from their dossier. Read the entries of the requested topics (or areas) in the given
+`dossier.json` (with `python3 -c` or `jq` if the file is large; do not load more than you need). For each:
+
+- Write a name of 2 to 7 words (areas: 3 to 10) that says what sets it apart, grounded in its `terms`,
+  `most_cited` titles and abstracts, and checked against `journals`, `categories` and `keywords`.
+- No generic names, no lists of terms, no duplicates among the batch or of the names you were told are taken;
+  use `linked_topics` to tell neighbours apart.
+- Add a one-line `reason` citing the evidence.
+
+Write the requested file as
+`{"topics": {"N": {"name": "...", "reason": "..."}}, "meta": {"by": "topic-namer", "model": "<your model>", "date": "YYYY-MM-DD"}}`
+(use `"areas"` instead of `"topics"` for areas) and reply with a short table of number and name. Do not run
+`citation-topics names`; the caller applies the files.

citation_topics-0.1.0/src/citation_topics/claude/skills/topic-namer/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: topic-namer
+description: Name the topics and areas found by citation-topics from their dossier (dossier.json) - short, specific names written from each topic's distinctive terms and most cited titles, checked against its journals, categories and keywords - and apply them with `citation-topics names`; carries names over from an earlier run first so only new topics are named. Use whenever a citation-topics output folder has unnamed topics, the user asks to name, rename or check topic names, or after `citation-topics run` and `describe`.
+---
+
+# Naming topics and areas
+
+Names are the one step that needs reading; everything else is computed. They are written by Claude, so they
+are not exactly repeatable: record who named them and when.
+
+## 1. Prepare
+
+- `OUT/dossier.json` must exist (`citation-topics describe INPUT OUT/`). Check its `missing` list: without
+  titles, keywords, journals or categories there is nothing to name from; tell the user and stop.
+- If an earlier run of the same or an overlapping list was named, carry its names over first:
+
+  ```bash
+  citation-topics compare OLD_OUT/ OUT/ CMP/      # CMP/names_carried.json: names + "to_name"
+  citation-topics names OUT/ CMP/names_carried.json
+  ```
+
+  Then name only the topics in `to_name`.
+
+## 2. Name
+
+For each topic, read in `dossier.json`: `terms` (with the share of its works using them), `most_cited` (titles,
+years, and the start of the abstract of the first three), `journals`, `categories`, `keywords`, `years`,
+`linked_topics`. Write:
+
+- **2 to 7 words**, specific to what sets the topic apart: "Neutrino oscillations", "Lattice QCD at finite
+  temperature", "Dark matter direct detection". Not generic ("Physics", "Theory"), not a list of every term.
+- Grounded in the dossier: the most cited titles and the top terms should agree; check the name against the
+  journals and categories. If they disagree, prefer what most of its works share (terms, categories) over a
+  single famous work.
+- Distinct: two topics never get the same name; when two are close, name what differs (method, object,
+  energy range, period). `linked_topics` shows the neighbours to tell apart.
+- A one-line `reason` citing the evidence (terms, titles, categories).
+
+Areas: broader names (3 to 10 words) covering their topics (`areas[].topics` lists them with their names).
+
+With many topics, work in batches of about 30. If the `topic-namer` agent is installed (`.claude/agents/`),
+give each batch to it: the topic numbers, the path of `dossier.json` and the file to write; check its names
+for duplicates afterwards.
+
+## 3. Apply
+
+Write `names.json`:
+
+```json
+{"topics": {"0": {"name": "...", "reason": "..."}},
+ "areas": {"0": {"name": "...", "reason": "..."}},
+ "meta": {"by": "topic-namer", "model": "<the model you are>", "date": "YYYY-MM-DD"}}
+```
+
+and merge it (it can be applied in parts; later files add to earlier ones):
+
+```bash
+citation-topics names OUT/ names.json
+citation-topics export OUT/              # VOSviewer and CSVs with the names
+```
+
+The command lists any topic still unnamed. Show the user a table of number, works and name, and say which
+names were carried over and which are new.

citation_topics-0.1.0/src/citation_topics/claude/skills/topics-compare/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: topics-compare
+description: Compare runs of citation-topics - agreement between seeds (NMI, ARI, medoid to keep) and where the topics of an earlier run or time window went in a later one (same, absorbed, split, scattered, with flows between topics and names carried over). Use whenever the user asks how stable the topics are, which seed to keep, how topics defined up to some year changed, how a new version of a list changes its topics, or wants to keep names from a previous run.
+---
+
+# Comparing runs of citation-topics
+
+## Seeds of one list
+
+```bash
+for s in 1 2 3 4; do citation-topics run INPUT OUT_s$s/ --seed $s; done    # same other parameters
+citation-topics agreement OUT_s1/ OUT_s2/ OUT_s3/ OUT_s4/
+```
+
+It prints NMI and ARI for every pair, for topics and areas, on the works all runs assign, and the medoid (the
+run with the highest mean topic NMI to the others): keep that one. Topic NMI around 0.85 between seeds is
+usual for large citation networks; much lower means the resolution is too high for the list or the list is
+small.
+
+## An earlier run against a later one
+
+The earlier run can be a time window of the same list (`run INPUT OLD/ --to-year 2010`) or a run of an older
+version of the list. Works are joined by id.
+
+```bash
+citation-topics compare OLD/ NEW/ CMP/
+```
+
+`CMP/flows.json`:
+
+- `old`: each earlier topic with its best new topic, `share` (of its works there), `back` (of that topic's
+  works that were in the earlier run) and `fate`: **same** (60% both ways), **absorbed** (60% one way),
+  **split** (two or more new topics with 15% each), **scattered**.
+- `new`: each new topic with its works not in the earlier run and the earlier topic it is the same as.
+- `flows`: `[old, new, works]` for every pair; `meta`: counts of fates, NMI and ARI.
+
+`CMP/names_carried.json` holds the names of the earlier topics that are the same as a new one, ready for
+`citation-topics names NEW/ CMP/names_carried.json`, and the topics left to name (skill `topic-namer`).
+
+Report the counts of each fate, NMI and ARI, the largest splits and merges by name, and how many new topics
+have most of their works after the earlier run.

citation_topics-0.1.0/src/citation_topics/claude/skills/topics-run/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: topics-run
+description: Build research topics and broad areas for any list of works (papers, theses, projects, patents) from their citation links with the citation-topics package - Leiden clustering of the direct-citation network as CWTS does for the OpenAlex topics, plus second and third topics of every work, a description of each topic, names, and VOSviewer/CSV exports. Use whenever the user has a JSON or JSON Lines list of works with ids and references and wants topics, fields, clusters or a classification of them, wants to rerun or tune the clustering, or asks what the output files mean.
+---
+
+# Topics of a list of works with citation-topics
+
+The package does the computation; this skill decides the parameters and explains the result. Every step
+writes into one output folder, `OUT/`.
+
+## 1. Check the input
+
+One JSON object per work, in a JSON array or JSON Lines file (`.gz` allowed):
+
+```json
+{"id": "W1", "references": ["W7", "W9"], "year": 2019, "title": "...", "abstract": "...",
+ "keywords": ["..."], "journal": "...", "categories": ["..."], "countries": ["..."], "authors": ["..."],
+ "citations": 41, "url": "https://..."}
+```
+
+Only `id` (unique) and `references` (ids of other works of the list) are required. Other names are read with
+`--id-field`, `--refs-field` and `--map NAME=FIELD` (for example `--map year=publication_year`). References to
+ids outside the list are ignored and counted. What each optional field adds:
+
+| Field | Adds |
+|---|---|
+| `year` | years of each topic, time windows (`--from-year`, `--to-year`), comparisons between epochs |
+| `title`, `abstract`, `keywords`, `journal`, `categories` | the description of each topic, hence its name |
+| `citations` | most cited works by that count (otherwise by citations inside the list) |
+| `countries`, `authors`, `url` | countries per topic in the description; kept for the boards; links |
+
+Before a long run, look at a few lines of the input and tell the user which optional fields it has and what
+will be missing.
+
+## 2. Run
+
+```bash
+citation-topics run INPUT OUT/ [--resolution 16] [--min-size 100] [--passes 20] [--seed 1] \
+    [--area-resolution 0.3] [--area-seeds 50]
+```
+
+The defaults are those of the HEP run this package was made from (1.9 million works, 304 topics, 6 areas).
+For another list, tune them:
+
+- `--min-size`: the smallest topic. Aim for topics of a few hundred to a few thousand works; for a list of
+  N works, start near N / 5,000 (at least 20).
+- `--resolution`: higher gives more, smaller topics. Run two or three values (for example 4, 8, 16) and compare
+  the number of topics, the share of links inside topics (`share_inside` in `topics.json`, higher is more
+  solid) and the unassigned works (`meta.json`).
+- `--area-resolution`: 0.3 gave the steadiest areas in the HEP run; try 0.2-0.5 if the areas look too few or
+  too many.
+- Seeds: Leiden depends on its random seed. For a result to keep, run 3-4 seeds (`--seed 1..4`, into different
+  folders) and keep the medoid with `citation-topics agreement OUT1 OUT2 OUT3 OUT4`.
+
+Run large lists in the background. Measured on 1.9 million works and 44 million links: `run` 45 minutes with
+20 passes (about 85 s per pass) and over 4 GB of memory; `describe` with titles 10 minutes and 4.4 GB. The same
+input, parameters and versions (all in `meta.json`) give the same topics.
+
+## 3. Describe and name
+
+```bash
+citation-topics describe INPUT OUT/ [--abstracts]     # OUT/dossier.json
+```
+
+Then follow the skill `topic-namer`: it names topics and areas from `dossier.json` and applies the names with
+`citation-topics names OUT/ names.json`. Without titles, keywords, journals or categories the dossier has only
+sizes, years and links; say so, and name only if the user can supply what a topic is about.
+
+## 4. Export
+
+```bash
+citation-topics export OUT/            # topics_vosviewer.json, topics_map.txt, topics_network.txt, CSVs
+```
+
+`topics_vosviewer.json` opens in VOSviewer Online: `https://app.vosviewer.com/?json=URL` with a public URL of
+the file.
+
+## Output files
+
+| File | Content |
+|---|---|
+| `works.jsonl.gz` | per work: `topic` and `area` from the clustering (null if none), `topics` (main, second, third with `score` = links to it / links to the main topic, capped at 1, and `links`), `n_links`, `inferred` (main topic from its links when the clustering left it out) |
+| `topics.json` | per topic: area, name, works, links inside and out, `share_inside`, years, most cited works |
+| `areas.json` | per area: name, works, topics, links, `share_inside` |
+| `meta.json` | parameters, versions, input MD5, network counts, which optional fields were present, quality |
+| `dossier.json` | description of each topic and area (after `describe`) |
+| `network.npz`, `clusters.npz` | arrays used by the other commands |
+
+Report the numbers that matter (topics, areas, works with a topic, unassigned, share of links inside) and
+which steps the missing fields ruled out.