ckb/.agents/modules/voice/README.md
Michał Kopeć c57ddceffd Template 2.2.0: voice and convert modules
- 2.1.0 new opt-in `voice` module (D-0020): skill ckb-voice rewrites every
  prose file written under apply_to (outputs/answers, documents, reports,
  PROJECT-OVERVIEW) in a voice whose profile is a wiki page,
  wiki/voice/<name>.md (type voice-profile); settings in ckb.yaml (mode,
  profile, writer, apply_to, skip, chat); frozen spans never change, vague
  claims flagged not cut; `writer:` delegates to an external rewriting
  skill such as a personal ghost-writer. ckb-module writes a manifest's
  default_config into the entry's config:. Eval ckb-module/install-voice.
- 2.2.0 new opt-in `convert` module (D-0021): skill ckb-convert and
  convert.py turn Markdown into Word/ODT/PDF/HTML through pandoc with a
  house style in templates/styles/; unit tests and eval
  ckb-module/install-convert.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 20:57:39 +01:00

2.9 KiB

voice module

Read this in: English | Polski

Opt-in. Install with "install the voice module"; remove with "uninstall the voice module". Nothing in here is active until installed.

What it does

Answers, documents and reports the KB writes for people outside it tend to read like a model wrote them. This module rewrites them in your voice before they're saved. The voice is a wiki page, wiki/voice/<name>.md, so the team can read it, review it and correct it like any other knowledge.

Skill Does
ckb-voice Rewrites outgoing text in a voice profile, builds a profile from sample documents, records "we never say X" as it comes up, and changes the settings.

Once installed, nothing changes until the first profile exists. Say "calibrate our writing style" and give it a few documents that sound right. From then on, every new file in outputs/answers/, outputs/documents/, outputs/reports/ and the project overview is written in that voice.

What changes and what doesn't

The voice changes wording: banned AI vocabulary, formulaic structure, hedging, flat rhythm, and the tone, formality and phrases your profile sets.

It never changes content. Frontmatter, ## Sources, ## Crux and every quote, ## Notes, contradiction markers, code, paths, links, numbers and names come out exactly as they went in. A rewrite that would alter one of them is rejected. A vague claim isn't cut, it's flagged for you. Wiki pages are never rewritten; the wiki stays plain.

Settings

In ckb.yaml, under the module's entry. Change them by asking ("set the voice mode to ask", "make board the default voice"):

config:
  mode: auto            # auto | ask (once per file) | off
  profile: house        # the default voice, wiki/voice/house.md
  writer: ckb-voice     # or another rewriting skill you have, e.g. ghost-writer
  apply_to: [outputs/answers/, outputs/documents/, outputs/reports/, PROJECT-OVERVIEW]
  skip: [outputs/okf/, outputs/starlight/]
  chat: false           # true = chat answers too

Which voice is used: one named in the request ("in the board voice"), else the voice: set in your own workload/profiles/ page ("use my own voice by default"), else profile.

Using your own rewriting skill

If you already have a rewriting skill you like, such as a personal ghost-writer in ~/.claude/skills/, set writer: ghost-writer. The module still picks the profile from the wiki and still guards the frozen parts; your skill does the rewriting. If the skill isn't installed on a teammate's machine, their sessions fall back to ckb-voice.

Safety

  • Profiles are committed. Everyone who clones the KB sees them. Keep samples to text you'd share with the team.
  • Third-party voices ("write like Feynman") are built from published text and keep only a few lines as a sample.
  • Uninstalling keeps the profiles. wiki/voice/ stays as knowledge; only the automatic rewrite stops.