Installing is one command that creates a project-local virtualenv under .claude/skills/.venv/, installs three packages (pyyaml · jsonschema · pytest), and leaves the system Python entirely untouched. Requirements: Linux, Python ≥ 3.9, git. No build step, no bundler, no global side effects.Cài đặt là một lệnh tạo virtualenv nội bộ dưới .claude/skills/.venv/, cài ba gói (pyyaml · jsonschema · pytest), và không đụng Python hệ thống. Yêu cầu: Linux, Python ≥ 3.9, git. Không bước build, không bundler, không tác dụng phụ toàn cục.

Install in one commandCài trong một lệnh

Run from the repo root after cloning. The script: ① create .claude/skills/.venv/ → ② pip install pyyaml · jsonschema · pytest into it → ③ verify the three imports resolve. No follow-up steps. The canonical invocation path is established by the script and locked for the lifetime of the project.Chạy từ gốc repo sau khi clone. Script: ① tạo .claude/skills/.venv/ → ② pip install pyyaml · jsonschema · pytest vào đó → ③ xác minh ba import resolve được. Không có bước nối tiếp. Đường gọi chuẩn được thiết lập bởi script và khóa cho suốt vòng đời dự án.

Verify — schema validationXác minh — kiểm tra schema

After installing, run the schema validator to confirm 119 files (rubrics, scorecards, references) parse cleanly against their JSON schemas. This is the structural proof that the toolkit imported, resolved its paths, and validated its data layer — with or without a character corpus. real outputSau khi cài, chạy bộ kiểm tra schema để xác nhận 119 file (rubric, scorecard, tài liệu tham khảo) parse sạch theo schema JSON. Đây là bằng chứng cấu trúc rằng toolkit đã import, phân giải đường dẫn, và xác minh tầng dữ liệu — có hay không có corpus nhân vật. đầu ra thật

Schema validation — 119 PASS, 0 FAIL, 3 SKIP
  ✓ All covered files conform to their schema.
PASS — exit 0

Degrade-clean — no corpus requiredXuống cấp êm — không cần corpus

The public toolkit ships no character corpus — docs/profiles/, docs/materials/, docs/graph/, docs/references/, and assets/ are absent by design. The system resolves subjects dynamically via paths.py reading docs/profiles/characters.yaml. Without that file:Toolkit công khai không kèm corpus nhân vật — docs/profiles/, docs/materials/, docs/graph/, docs/references/, và assets/ vắng mặt theo thiết kế. Hệ thống phân giải nhân vật động qua paths.py đọc docs/profiles/characters.yaml. Không có file đó:

To add your own corpus: create docs/profiles/characters.yaml with a list of character slugs. The tooling resolves all paths dynamically — no hardcoding needed. The private repo pattern places the full corpus in the same directory structure; the public toolkit is structurally identical.Để thêm corpus của bạn: tạo docs/profiles/characters.yaml với danh sách slug nhân vật. Công cụ phân giải tất cả đường dẫn động — không hardcode. Mô hình repo riêng đặt corpus đầy đủ trong cùng cấu trúc thư mục; toolkit công khai giống hệt về cấu trúc.

Run the full deterministic suiteChạy bộ kiểm thử tất định đầy đủ

After installing and validating, run the complete deterministic gate. No API key. No external calls. The -m 'not gemini' marker excludes the 34 live-LLM tests. Without a roster: ~665 pass, ~175 skip. real outputSau khi cài và xác minh, chạy cổng tất định đầy đủ. Không API key. Không gọi mạng. Tham số -m 'not gemini' loại trừ 34 test LLM thật. Không có roster: ~665 đạt, ~175 bỏ qua. đầu ra thật

$ pytest tests/ -q -m 'not gemini'
1100 passed, 34 deselected, 2 warnings in 55.77s

→ deterministic suite green · 0 network calls · corpus-dependent tests skip cleanly

CI gatesCổng CI

Three GitHub Actions workflows run on every push. All deterministic — no API key needed in CI.Ba workflow GitHub Actions chạy mỗi lần push. Tất cả tất định — không cần API key trong CI.

License + distributionGiấy phép + phân phối

FAQHỏi đáp