nihaisha: an Agent Skill for retrieving Ni Haisha's TCM course material

The problem nihaisha targets: course material that cannot be looked up

Ni Haisha's teaching exists as long lecture series: Shanghan Lun, Jingui Yaolue, Zhongjing Xinfa, clinical case discussions, Bagang Bianzheng, Fuyang Forum, Yijinjing, the Liang Dong dialogues, the Stanford talk, Tianji, Huangdi Neijing, Shennong Bencao and the acupuncture course. The README lists all of these as covered modules. Studying them means remembering roughly where a formula discussion happened and what was said around it, and a plain transcript search does not answer a question phrased as a symptom.

The project's answer is an Agent Skill. Once installed, the agent takes a colloquial complaint such as feeling cold with a cold, cold hands and feet, diarrhoea, or not sleeping, and converts it into what the README calls dividing-line questions before searching course terminology. The stated audience is learners: people reviewing lectures, comparing formulas, looking up acupoints or herb properties, and assembling revision notes. The README's scenario table is explicit that real clinical medication decisions are not a fit, and that the Skill does not offer personal diagnosis, prescriptions, dosages or self-medication advice.

How the Skill is structured: text references, screenshot evidence, PDF evidence

The repository is a reference tree, not a database service. Top-level entries include SKILL.md, a references directory, an assets directory, docs, evals, agents, scripts and a Python package named nihaisha_kg. Each course module has a markdown text file plus, for most modules, a separate screenshot evidence file. The README gives counts: 649 screenshots for Shanghan Lun, 656 for Jingui Yaolue, 68 for Zhongjing Xinfa, 88 for clinical cases, 33 representative frames for Bagang Bianzheng, 37 for Fuyang Forum, 28 for Yijinjing, and 2986 screenshot evidence entries in total, compressed to WebP inside the repository. Those images are retrievable by formula name, acupoint, lesson number, pathogenesis or time point.

On top of the screenshot layer sits a PDF evidence layer at references/pdf-evidence/, derived from proofread course PDFs and organised by course, page number and keyword. The README describes a two-stage retrieval behaviour: when the main course material matches a topic, a secondary search runs over supplementary material, and those results are listed separately rather than merged into the course text. Supplementary books recommended by Ni Haisha are marked as recommended supplementary material rather than as his own words. That separation is the design decision worth noticing. It costs an extra retrieval pass and makes answers longer, but it keeps provenance legible, which matters when the whole point is tracing a claim back to a page.

Installing nihaisha as a Skill and running a first lookup

The repository ships an installer script at the top level, install_as_skill.sh. The README does not reproduce the script's contents, so read it before running it and check which directory it writes into for your agent. If you prefer to place the Skill manually, copy the repository into the Skill directory your agent reads, keeping SKILL.md and the references tree together, because the reference paths in SKILL.md are relative to the repository root.

bash install_as_skill.sh

The Python package is a separate concern. pyproject.toml names it nihaisha-rag-prototype, requires Python 3.11 or newer, and declares a single base dependency, requests. That is the text and knowledge search path, and the .env.example file states plainly that text and knowledge search need no API key. Optional extras exist for the vector path: faiss, runtime (faiss-cpu) and local (FlagEmbedding).

pip install -e .
pip install -e '.[runtime]'

The environment file documents the remote embedding backend. Copy .env.example to .env and keep .env uncommitted; the runtime parses the nearest .env as KEY=VALUE without executing a shell, and exported values take precedence.

cp .env.example .env

SILICONFLOW_API_KEY=
SILICONFLOW_RERANK_MODEL=BAAI/bge-reranker-v2-m3
LOCAL_BGE_M3_USE_FP16=false

A first real use is a course lookup rather than a clinical question. Ask the agent something like which lessons discuss a given formula in Shanghan Lun, then follow the returned citation into references/shanghanlun.md and, if a screenshot is cited, into the corresponding WebP. What you should see is a lesson or page reference and a separate supplementary block, not a single blended answer. If your agent returns prose with no path, the Skill is not being read.

Where nihaisha fails: the withdrawn RAG mode and the boundary scores

The largest limitation is stated in the README's own update log. On 2026-08-08 the RAG and knowledge graph mode was taken offline after user feedback, and while it is down the mode is unavailable and no data package is downloadable. The full description and flow diagrams remain in docs/RAG_GRAPH_MODE.md, and previously downloaded local data under data/pdf_rag_bge_m3/ can be kept for reuse if it returns. The 2026-07-18 entry put the full resource at roughly 3.68 GB and warned about disk space. Anyone reading the feature list and expecting vector retrieval should read the withdrawal notice first.

The evaluation table is worth reading the same way. The README reports 240 questions with each answer generated and blind-scored three times per channel, and it labels the figures as historical data from before the RAG withdrawal, showing ordinary Skill results only. Overall answer score is 91.4 percent. Two numbers stand out against that average: capability boundary pass rate at 8.3 percent (5 of 60) and same-question consistency at 62.5 percent (75 of 120). The README also records one serious safety flag across 720 answers and seven observed source misattributions across 513. A high average with a very low boundary score means the Skill is much better at finding material than at recognising when it should refuse, which is exactly the failure mode that matters for a medical corpus. The project invites TCM practitioners to review the questions, rubric and citations through Issues, which is an admission that the scoring has not been validated clinically.

nihaisha compared with a plain RAG stack over the same PDFs

The obvious alternative is building your own retrieval pipeline over the same course PDFs: chunk the text, embed it with a model such as BAAI/bge-m3, store vectors in a local index, and let a general agent answer. That approach is more flexible and gives you control over chunking and reranking, and the project itself points in that direction, since pyproject.toml declares faiss-cpu and FlagEmbedding as optional extras and .env.example names SiliconFlow's BAAI/bge-m3 for query embedding and BAAI/bge-reranker-v2-m3 for reranking.

The difference is what has already been done for you. A self-built index over raw transcripts inherits the transcription errors the project spent effort correcting, including the 2026-06-25 entry describing systematic fixes to terms, formula names, acupoint names and classical citations, and the 2026-07-15 entry moving executable dosage, decoction, needling, bloodletting, moxibustion and toxic-drug operations out of the text layer into an evidence layer that keeps the source frame but is uniformly marked as not to be followed. A generic pipeline will happily answer a dosage question. This Skill is built to route it elsewhere. The trade-off is the opposite direction: you inherit the project's module boundaries, its reference file layout and its current RAG outage, and you cannot easily swap in a different corpus without rebuilding the evidence indexes.

Maintenance, packaging and licence status

The repository is not archived, and the last push was on 2026-09-16, so the project is being touched frequently. The README's own banner asks users to check back periodically and install the latest version, which is a reasonable signal that interfaces and reference paths can move between versions. There are no releases retrieved, so installation means cloning the repository or running install_as_skill.sh from a checkout rather than pulling a tagged artefact. Pin a commit if you need reproducibility.

The licence is not stated in the repository, and pyproject.toml carries no licence field. That is a real gap for anyone planning to redistribute the Skill, bundle it into an internal tool or ship it alongside commercial software. The corpus also mixes layers of different origin: Ni Haisha's own course material, supplementary books the README marks as recommended rather than authored, and an external acupuncture safety reference added on 2026-08-03 from a 2006 Japanese journal paper, credited to a named physician and marked in the Skill as external reference rather than course text. Treat the licence question as unresolved until the repository states one.

Editorial conclusion

Adopt this if you are studying Ni Haisha's recorded courses and want agent-assisted retrieval with page-level and screenshot-level citations, and if you are comfortable installing a Skill into Claude Code, Codex or OpenClaw. Do not adopt it if you want dosage, needling depth or personal diagnosis guidance: the README states the Skill does not provide personal diagnosis, prescriptions, dosages or self-medication advice, and executable dosing and needling detail has been moved into an evidence layer explicitly marked as not to be followed. Before relying on it, verify three things: which Skill directory your agent actually reads, whether the referenced screenshot and PDF evidence files are present in your clone, and the current status of the RAG and knowledge graph mode, which the README says was taken offline on 2026-08-08 and whose data package is not downloadable while it is down.

Frequently asked questions

Official sources

1. Issues
2. JuneYaooo/nihaisha-nishi-tcm on GitHub
3. README