feat(skill): plan talk and document decks and review Japanese wording

[baseballyama]

Summary

Decks written with the slide skill read as machine-made in Japanese. The problems were stock phrases, dashes, 「効く」, 「ラベル：説明」 bullets, and pages that contradict each other. The skill now makes the agent decide first whether the deck is a talk or a document, then apply matching story and headline rules. It also adds Japanese wording rules and a review step before delivery.

Motivation

Several people have published slide skills for Japanese decks. After surveying them, the maintainer chose to combine these:

• coji/natural-japanese for wording
• minorun365's slide-story and writing guide for talk structure
• tyroneross/pyramid-principle for document structure
• carnot-tech/consulting-pptx-skill for headlines, bullets and tables

A real 60-page conference deck was rebuilt from scratch in both modes to test the rules. The findings from those builds and their fresh-eye reviews are folded back in. The largest lesson was that reviewers mostly caught facts that differ between pages, not awkward words, so the review step now includes a cross-page consistency check.

Changes

• skill/SKILL.md: add a step to plan the story and the words (talk vs document; never invent facts; name headlines Headline). "Check and deliver" now runs the review. Add a fallback preview route via soffice and pdftoppm.
• skill/references/story-talk.md (new):
  • no agenda and no upfront answer
  • question dividers
  • one message per slide
  • a mix of headline forms with reference ranges
  • timing
  • a closing call to action
• skill/references/story-document.md (new):
  • answer first (SCQA)
  • assertion headlines with two tests
  • Japanese headline length and plain form
  • rules for body text and tables
  • how to turn a talk deck into a document
• skill/references/writing-ja.md (new): a table of expressions to avoid, with fixes; deck-level habits; notation; rules for revising an existing deck.
• skill/references/review.md (new):
  1. extract text and flags
  2. judge each flag
  3. read the headline track
  4. check numbers, mechanisms and terms across pages
  5. fresh-eye review by a context-free agent, with an adoption table
• skill/scripts/deck-text.mjs (new): prints the headline track, mode-specific metrics and wording flags, including speaker notes. It resolves @office-kit/pptx from the slide project.
• skill/references/tsx.md: add authoring pitfalls hit in practice, such as anchor values, Color, exactOptionalPropertyTypes and table fills, plus a page-number pattern.
• skill/references/sources.md (new): upstream commits and licenses (MIT and Apache-2.0).
• README and the consulting-deck-design skill link to the new references.

Testing

• node --test packages/dev/test/skill-deck-text.test.mjs (new) builds a deck through initProject and buildDeck, runs the script from the project, and checks that:
  • named headlines are found
  • the ？ ratio is reported
  • the 効く / dash / 切る flags fire, and also fire in notes
  • 有効 is not flagged
  • an invalid --mode is rejected
• npx oxfmt --check . and npx oxlint are clean.
• packages/dev/test/authoring.test.mjs, which builds the tsx.md agenda example, passes. Its separate "initialized TSX typechecks" case fails in my local worktree on unmodified main too, because module resolution fails from the temp directory, so it is unrelated to this change.
• Manual: talk (60 slides) and document (37 pages) versions of a real deck were built with the skill, rendered, reviewed and fixed.

Breaking changes

None. This only changes the agent skill documents; no package API changes, so there is no changeset.

Checklist

• I have read CLAUDE.md and followed the project's conventions.
• I have added or updated tests for the change.
• I have added or updated documentation where user-visible behavior changed.
• If this is a breaking change, I have added a changeset / CHANGELOG entry and
  flagged it above.
• I have re-read my own diff and removed dead code, debug prints, and stale comments.
• If I used an LLM to draft this PR, I have verified each change myself, the PR
  represents real work that warrants a maintainer's review, and I am willing to
  defend each line in review.

🤖 Generated with Claude Code

https://claude.ai/code/session_0116eREiYfHTFLy5Eu3nwh5f