CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Claude Code skill marketplace for academic research on Chinese historical and geographical data. Each skill wraps an external API and is primarily documentation-driven. Skills are registered in .claude-plugin/marketplace.json.

Repository Structure

Each skill follows a consistent layout:

<skill-name>/
├── SKILL.md                  # Main documentation (YAML frontmatter + usage guide)
└── references/
    └── api_reference.md      # Technical API spec (endpoints, params, responses)

Optional: scripts/ for utility code (Python 3, standard library only, unless the skill says otherwise) and tests/ for offline tests.

Current Skills

.claude-plugin/marketplace.json is the list of published skills (30 as of 2026-11-06). The README tables group them by topic. Keep both in step when adding or removing a skill. Folders that are not in marketplace.json (for example columbia-clio, which is retired and gitignored) are not published.

Build & Development

There is no build system, package manager, or CI pipeline. Many skills have Python code in scripts/. Skills with code have offline tests in tests/ (unittest, with a fake urlopen). Run them per skill:

cd <skill> && python3 -m unittest discover -s tests

tools/check_alma_sync.py checks that the five Alma SRU client copies match (see below).

Conventions

Adding a New Skill

1. Create a directory with a hyphenated name (e.g., new-skill-name/)
2. Add SKILL.md with YAML frontmatter (name, description, version, license, author, contributors)
3. Add references/api_reference.md with endpoint details, parameters, and examples
4. Register in .claude-plugin/marketplace.json under plugins
5. End SKILL.md with the standard Feedback and Citation section (copy it from any existing skill and change the skill name)

SKILL.md Structure

Each SKILL.md follows this pattern: Overview → When to Use → Quick Start / Workflow → Best Practices → Example Code → Resources → Feedback and Citation.

When changing a skill, bump its version in both SKILL.md and marketplace.json so installed copies update.

The Alma SRU client exists in five copies (alma-sru-catalogs/scripts/alma_sru.py is the reference; the umich, princeton, yale, and pitt skills keep their own copies so each installs alone). Make shared fixes in all five, then run python tools/check_alma_sync.py.

API Etiquette (enforced across all skills)

• Rate-limit requests (0.5–1s minimum between calls)
• Set User-Agent headers with contact info (required by Wikidata Vector DB and WDQS)
• Respect HTTP 429 / Retry-After headers
• Use maxlag parameter for Wikidata Action API queries

Text Encoding

• UTF-8 for all Chinese characters — do not URL-encode Chinese text into hex
• URL-encode spaces and special characters normally

API Quirks

• CHGIS TGAZ ID lookups: Format is in the URL path (/placename/json/{id}), NOT a query param. The ?fmt=json param only works for faceted search.
• CHGIS TGAZ search: Uses prefix/wildcard matching (beijing matches 北京路, 北井县, etc.)
• CBDB JSON path: Response data is deeply nested under Package.PersonAuthority.PersonInfo.Person
• Wikidata Vector DB: Requires a descriptive User-Agent header or returns 403

Python Style (wikidata_api.py)

• Type hints on all signatures
• Private methods prefixed with _
• Rate limiting and retry with exponential backoff built in
• Environment variable WIKIDATA_VECTORDB_API_SECRET for vector DB auth