Kami Documentation

Technical Documentation: tw93/Kami

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

Why Copy Chapter

Kami (紙, かみ) means "paper" in Japanese. It gives AI agents layout rules and templates for PDF, PNG, and editable PowerPoint output, with eight built-in document templates and a product landing page.

As the delivery piece of the trilogy, Kami works alongside Kaku (書く), built for writing code, and Waza (技), built around engineering habits, so technical work is not only logically rigorous but also visually compelling.

Showcase Copy Chapter

Sample PDFs in several formats and languages. Click any preview to open it.

|
Resume · English
Founder resume, 2 pages |
One-Pager · 中文
Kami 介绍 · 白底打印版 |
Equity Report · 中文
Tesla Q1 2026 财报点评 |
Slides · English
Agent keynote, 8 slides |

| --- | --- | --- | --- |
|
One-Pager · English
Mole product brief, 1 page |
Letter · 中文
推荐信, 1 页 |
Changelog · English
Mole v1.7.1 release notes |
Portfolio · 日本語
Kaku ターミナル作品集 · 7 ページ |

Install Copy Chapter

Claude Code, Codex, Cursor, and other agents

npx skills add tw93/kami -a claude-code codex cursor -g -y

One copy lands in ~/.agents/skills, the shared skills directory. Claude Code is symlinked in; Codex, Cursor, and every other agent that reads that directory picks Kami up as /kami. Update with npx skills update -g -y.

Or ask your agent:

Install Kami for me by reading https://kami.tw93.fun/llms.txt

Host plugin, if you prefer the host's own update command (namespaced as /kami:kami, Claude Code v2.1.142 or newer):

# Claude Code (update: claude plugin update kami)
/plugin marketplace add tw93/kami
/plugin install kami@kami

# Codex (update: codex plugin marketplace upgrade kami, then codex plugin add kami@kami)
codex plugin marketplace add tw93/kami
codex plugin add kami@kami

Claude Desktop: download the release asset kami.zip, not GitHub's source ZIP, open Customize > Skills > "+" > Create skill, and upload it. To update, click "..." on the skill card, choose Replace, and upload the latest ZIP.

Large CJK fonts stay out of every package: skills/kami/scripts/ensure-fonts.sh recovers missing Chinese or Korean fonts into the user font directory, and in a repository checkout it copies the tracked fonts into the skill so templates load them locally before falling back to the jsDelivr CDN.

On Windows, run Kami inside WSL (Ubuntu): the helper scripts are Bash, and WeasyPrint on native Windows also needs the GTK/Pango runtime installed separately.

Kami also runs a quiet version check at most once a day and tells you in chat when a newer published release is out. It writes a marker in the local XDG cache directory, then resolves GitHub's latest public release; it uploads no user document or task content and fails silently when offline or when no cache home is available.

Use Copy Chapter

Supported Languages Copy Section

English and Chinese have the most complete support. Japanese and Korean use language-specific font fallbacks and layout adjustments, with each output checked before delivery. Each language uses a single serif font for the whole page, with font terms under License:

The skill auto-triggers from natural requests, no slash command needed. Example prompts by language:

• English: make a one-pager for my startup / turn this research into a long doc / write a formal letter / make a portfolio of my projects / build me a resume / design a slide deck for my talk / make this talk as a Marp deck / build a landing page for my app
• 中文: 帮我做一份一页纸 / 帮我排版一份长文档 / 帮我写一封正式信件 / 帮我做一份作品集 / 帮我做一份简历 / 帮我做一套演讲幻灯片 / 帮我做一份 Markdown 风格的演示稿 / 帮我做一个产品落地页
• 日本語: スタートアップ向けの一枚資料を作って / この調査を長文レポートに整えて / 正式な依頼文を作って / プロジェクト作品集を作って / 履歴書を作って / 登壇用スライドを作って / Marp で登壇スライドを作って / アプリのランディングページを作って
• 한국어: 스타트업 원페이저를 만들어줘 / 이 리서치를 장문 문서로 정리해줘 / 정식 레터를 작성해줘 / 프로젝트 포트폴리오를 만들어줘 / 이력서를 만들어줘 / 발표용 슬라이드를 만들어줘 / Marp 슬라이드로 만들어줘 / 앱 랜딩 페이지를 만들어줘

Brand profile (optional)

Create ~/.config/kami/brand.md to persist identity, brand, defaults, and writing habits, so you don't repeat your preferences for each document. The file has YAML frontmatter for structured fields like name, role, email, brand color, language, page size, and tone, plus a Markdown body for freeform notes. Kami uses these settings where the current request leaves a choice open; explicit instructions always take priority. See brand.example.md for a full template.

Design Copy Chapter

The defaults are a warm parchment background (#f5f4ed), ink-blue accents (#1B365D), and serif fonts. Templates use type size and spacing to separate titles, body text, and notes. You can adjust the defaults for your brand.

• Templates. Eight document templates: One-Pager, Long Doc, Letter, Portfolio, Resume, Slides, Equity Report, and Changelog, plus a Landing Page system, in EN, CN, and KO. Kami picks the right variant based on the language you write in.
• Diagrams. Eighteen inline SVG types, including a report-scale architecture board. Sequence, class, and ER can be authored from Mermaid text: beautiful-mermaid renders the SVG and skills/kami/scripts/mermaid_normalize.py re-themes it to the Kami palette and makes it WeasyPrint-safe, no Node bundled.
• Slides. Three rendering paths: WeasyPrint HTML to PDF by default, python-pptx for editable PPTX on request, and a Marp variant in skills/kami/assets/templates/marp/ for Markdown-first decks.
• Code. Pygments-based syntax highlighting when Pygments is installed; without it, PDFs still render and code stays monochrome.
• Verification. Content schemas check structure before layout; coverage checks look for content missing from the filled page. A structured brief records the audience and requirements, and page images support the final visual review.
• MCP. A zero-dependency MCP server (skills/kami/scripts/mcp_server.py) exposes capability diagnosis, render, structured check, and screenshot tools, so any MCP-capable agent can drive Kami as an engine without loading the full skill prompt. Render only trusted local HTML: referenced file, HTTP, and HTTPS resources load with the MCP process's permissions.
• Print. Parchment is the default canvas; an opt-in white-paper variant flips any document to a white background for home or office printers, keeping warm backgrounds in cards and tables. The one-page Kami intro (Chinese) is rendered with this variant; recipe in production.md.

Full spec: design.md. Cheatsheet: CHEATSHEET.md.

Beyond Documents Copy Chapter

|
Kami · landing page
Design system homepage |
Mole · landing page
macOS system utility | Architecture redraw · English
SpatialVLA Figure 1, schematic | Evidence layout · 中文
Tesla Optimus 专利图一览 |

| --- | --- | --- | --- |

The same layout rules also work for landing pages and prompts for AI image tools. Landing pages ship as deployable multilingual sites. Illustrations use the host's own image generation when that capability is available; otherwise Kami outputs the same complete brief for use in an image model.

Redraw this as a clean editorial diagram. Background: warm parchment (#f5f4ed), never pure white. One accent only, ink blue (#1B365D); everything else in warm gray with a yellow-brown undertone, no other colors. Thin single-line geometric strokes and simple flat icons. No gradients, no drop shadows, no 3D. Labels in a serif typeface. Generous whitespace, calm and composed, like a figure in a well-typeset report.

_{The two illustrations above were rendered by ChatGPT Images in a single pass, with no manual touch-up.}

Background Copy Chapter

I like investing in US equities and ask Claude to write research reports all the time. Every output landed in the same default-doc look: gray, flat, a different layout each session. The structure was hard to scan, the formatting felt dated, and nothing about the page made me want to keep reading. So I started fixing the typography, the palette, the spacing, one rule at a time, until the report became a page I actually enjoyed.

Later I needed to present "The Agent You Don't Know: Principles, Architecture and Engineering Practice." I already had the document and didn't want to build slides from scratch, so I used Claude Design to lay it out in my own style, tweaked it round after round, and eventually got it to a place I was happy with. That process added inline SVG charts, a unified warm palette, and a tighter editorial rhythm. It kept growing until it covered every document I regularly ship, so I collected the templates and rules into Kami.

Support Copy Chapter

• The most direct way to support me is getting Mole for Mac, my paid Mac cleanup app
• If Kami helped you, give it a star, share it, or open an issue or PR
• I have two cats, TangYuan and Coke, and if Kami has been useful, you can feed them canned food 🥩

These lovely people already did 🐱

License Copy Chapter

MIT License for Kami code and templates. Please feel free to use and contribute to the development.

Fonts: TsangerJinKai02 is free for personal use only; commercial use requires a license from tsanger.cn. Source Han Serif K and JetBrains Mono are under the OFL. Charter and YuMincho come from the operating system and are not shipped with Kami; CJK fallbacks are system-bundled or open-licensed.

Release (`docs/release.md`) Copy Section

Release (Notes · Flow · Demo Assets)

Read this when cutting or refreshing a release, or when regenerating tracked demo
screenshots. Everyday template, script, and site work does not need it.

Part 1 · Release notes Copy Chapter

• Read the previous published release first for the structure, not the prose:
  gh release view $(gh release list -R tw93/Kami --limit 1 --json tagName --jq '.[0].tagName') -R tw93/Kami.
  Mirror its exact shape (centered logo block, ### Changelog, ### 更新日志,
  ### Thanks, closing tagline blockquote). Do not rebuild the shape from memory. The
  wording of the items comes from the voice reference below; releases before V1.16.0
  carry the compressed one-line form that this section replaced.

• Title shape: V<x.y.z> <Two-Word Codename>, for example V1.7.2 Cleaner Resumes.

• Body: centered logo block + ### Changelog (English numbered list) + ### 更新日志
  (Chinese numbered list) + the closing tagline line.

• Bilingual and one-to-one: English item N maps to Chinese item N, with the count
  determined by distinct user-visible changes. At most five items. Fewer, denser items
  beat padding the list: group the commits by the capability a user gains, and drop
  anything that shipped to the site rather than into the package, since a site change
  is already live and needs no upgrade. Merging means folding the smaller outcomes into
  a larger one, never deleting them to hit the count.

• Shape of one item: the bold label is a short topic, 4 to 10 Chinese characters or
  under 25 English ("长文目录页码", "Long-doc page numbers"), never a bolded sentence
  and never two outcomes joined by a comma. Everything the reader needs sits after the
  colon, unbolded: what used to happen, what happens now, and where the new behavior
  stops. Name the real nouns, the template, the flag, the command. A noun label is only
  a failure when the text after it is one compressed clause; carry the before and after
  there and the short label reads fine. tw93/mole-mac v1.4.0 is the label reference.
  The label names the capability, not an action slogan or an adjective: 统一交付检查
  over 一条命令收尾, 按需加载规范 over 技能更轻. The before state is behavior a user
  could have observed; an observation from the maintainer's own eval runs ("resume
  balance was often skipped") belongs in the commit, not the note. The after state names
  the concrete output (给出 READY 或 NOT READY 结论), never a paraphrase of it
  (给出能否交付的结论).

• One item is one sentence, in both languages. Every Chinese item carries exactly one
  。 at the end and chains its clauses with ， and 、; do not close each clause
  with its own full stop. Measured across the last three tw93/Mole releases, 19 of 19
  Chinese items have a single full stop and two to four commas. Length, from the same
  sample: Chinese 60 to 100 characters, median 83; English 150 to 290, median 213. A
  one-line item is the failure mode, and so is a three-sentence one.

• Measure, do not estimate. Both times these numbers were eyeballed the result was
  wrong by 30 percent, and V1.16.0 went out three times before it matched:

  bash Copy

  gh release view V1.55.0 -R tw93/Mole --json body --jq .body | \
    grep -E '^[0-9]+\. ' | awk '{print length": "$0}'

• Register is plain technical writing, in both languages. The first V1.16.0 rewrite
  overcorrected from generated prose into spoken Chinese: 照单全收, 顶上, 开工,
  不好看, 不再动你已有的; V1.17.0 needed a second pass for 收尾, 跑完, 漏掉, 落到.
  Mole uses none of that. No idioms, no spoken verbs, no second-person instruction
  voice; write 解析失败 over 没成功, 端点未正确附着 over 端点接错, 前置提问 over
  开工前问, 执行全部检查 over 跑完, 回退为黑体 over 落到黑体. Precise technical nouns
  are what keeps an item from reading as either a press release or a chat message.

• The voice reference is gh release view <tag> -R tw93/Mole, not Kami's own older
  releases. A label that is an abstract category, an item with no before-and-after, and
  a subtitle that lists this release's themes are the three tells of a generated note.
  The subtitle stays the product's fixed line, the way Mole keeps one across releases.

• Close with ### Thanks naming the issue reporters and PR contributors of this cycle
  when there are any: gh issue list --state closed and gh pr list --state merged
  filtered to the previous tag's date.

• Generate the scaffold, then rewrite it:
  python3 scripts/draft-release-notes.py V..HEAD --version V<new> --title "<Codename>".
  Regroup the raw commit list into product-themed bullets; never paste commit subjects.

Part 2 · Release flow Copy Chapter

• bash scripts/package-skill.sh dist/kami.zip packages skills/kami as a top-level
  kami/ skill folder; its audit gate rejects large fonts, rendered examples, tests,
  and cache files. dist/ is ignored: the archive is never tracked, release.yml
  builds it from the tagged commit and uploads it.

• Any change under skills/kami that users should receive on Claude Desktop needs a
  new version tag; do not replace a published version with different payloads.

• Verify the published asset by content, not by page text: download the uploaded
  kami.zip and compare ZIP entry names plus per-entry SHA-256 digests against a
  fresh local bash scripts/package-skill.sh build of the same commit. File size or
  container SHA alone proves nothing.

• README and public site download links point at
  https://github.com/tw93/kami/releases/latest/download/kami.zip. Even small package
  changes require a new patch version so update checks and downloaded contents agree.

• Confirm remote CI is green on the exact commit about to be tagged, and read the
  headSha back rather than trusting the newest row:

  bash Copy

  gh run list --workflow=check.yml --limit 20 \
    --json headSha,headBranch,event,status,conclusion

  A full local pass is not the verdict. V1.11.0 shipped while CI had been red for
  seven consecutive runs, because a test read assets/examples/one-pager.pdf, which
  is gitignored build output: it passed on any machine that had run a build and
  failed on every fresh checkout. Local green means "my working copy is fine", CI
  green means "a clean checkout is fine", and only a successful push run on main
  proves the tag candidate entered the release branch. Poll the structured status;
  piping gh run watch into tail swallows
  the exit code and reports an unfinished or failed run as passing.

• The release workflow enforces the same contract before it can create an asset:
  TAG == V$(cat skills/kami/VERSION), the tag resolves to the checked-out commit, the commit is
  reachable from origin/main, an exact-SHA check.yml run from a main push is
  complete and successful, and, when a same-version asset already exists, the rebuilt
  archive has the same entry names and per-entry SHA-256 payloads as the published one.
  Immediately before upload, it also confirms the remote tag still resolves to the
  reviewed SHA. Keep these as hard gates; a manual dispatch is not an override.

• Create a version tag only when the maintainer explicitly asks for a versioned
  release, and tag the commit whose skills/kami is the final content.

• On tag push, .github/workflows/release.yml builds the archive from that commit and attaches it,
  creates the release if missing, refuses to replace a different same-version asset,
  and adds and verifies the house-style reactions. An idempotent rerun may keep an
  existing asset only when its entry names and payloads are identical. Do not
  gh release create by hand: let CI create the placeholder, then set the real title
  and notes with
  gh release edit V<x> --title "V<x> <Codename>" --notes-file <file>.

• If reactions are missing (older release, CI skipped), add them manually:
  rid=$(gh api repos/tw93/Kami/releases/tags/V<x> --jq .id); for r in +1 eyes heart hooray laugh rocket; do gh api -X POST repos/tw93/Kami/releases/$rid/reactions -f content="$r"; done.

• Reactions are part of publish completion. After the release is live, read them back
  with gh api repos/tw93/Kami/releases/$rid/reactions --jq '.[].content' and confirm
  all six positive reactions are present. Never add -1 or confused; a negative
  reaction on our own release reads as self-deprecation.

Part 3 · Demo screenshots Copy Chapter

Every demo PNG under site/assets/demos/ is 1241x1754px, the first A4 portrait page at
150dpi. Regenerate them whenever the demo's PDF changes.

Portrait documents (one-pager / letter / resume / portfolio / long-doc /
equity-report), capture page 1:

pdftoppm -r 150 -f 1 -l 1 -png <pdf> /tmp/p && cp /tmp/p-1.png <target>.png

Landscape slides: capture the first 2 pages, resize each to 867px high, add a 20px
parchment gap, then extend to the portrait frame:

pdftoppm -r 150 -f 1 -l 2 -png <pdf> /tmp/sl
magick /tmp/sl-1.png -resize x867 /tmp/sl1.png
magick /tmp/sl-2.png -resize x867 /tmp/sl2.png
magick -size $(identify -format '%w' /tmp/sl1.png)x20 xc:'#f5f4ed' /tmp/gap.png
magick /tmp/sl1.png /tmp/gap.png /tmp/sl2.png -append /tmp/stacked.png
magick /tmp/stacked.png -gravity Center -background '#f5f4ed' -extent 1241x1754 <target>.png

Before replacing a tracked PNG, confirm the source PDF used an intended primary or
listed fallback font (not DejaVu or Bitstream Vera) and that the captured page has
representative content with no placeholders or missing assets.

--- METRICS ---

• Files Extracted: 2
• Estimated Token Budget: ~5787 tokens
• Canonical Reference: https://codewiki.google/github.com/tw93/Kami