ckb/.agents/modules/voice/skills/ckb-voice/SKILL.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

9.8 KiB
Raw Blame History

name description
ckb-voice Rewrite text the KB sends out (kept answers, documents, reports, the project overview) in a writing voice whose profile lives in wiki/voice/, and maintain those profiles and the voice settings. Runs before any prose file is written under the configured outputs paths, whichever skill drafted it. Use for "rewrite this in our voice", "use the <name> voice", "make this sound less AI", "humanize this", "calibrate our writing style", "create a voice profile", "update the house voice", "list voices", "set the voice mode to ask", "turn the voice off", "use my own voice by default".

Voice skill

Purpose

Everything this KB hands to people outside it should read like the team wrote it, not like a model did. The rules for how to write are generic and ship here; the voice itself (tone, formality, words to keep and avoid, samples) is knowledge the team owns, so it is a wiki page anyone can review and correct: wiki/voice/<name>.md.

Two jobs:

  1. Apply a voice to a draft before it leaves the KB (Steps 1–5).
  2. Maintain profiles and settings (the sections after Step 5).

Settings

Under the voice entry of kb_modules: in ckb.yaml, written by ckb-module on install from the manifest's default_config:

kb_modules:
  - name: voice
    version: 1.0.0
    installed_on: YYYY-MM-DD
    config:
      mode: auto            # auto | ask | off
      profile: house        # default profile, wiki/voice/house.md
      writer: ckb-voice     # or another installed rewriting skill
      apply_to: [outputs/answers/, outputs/documents/, outputs/reports/, PROJECT-OVERVIEW]
      skip: [outputs/okf/, outputs/starlight/]
      chat: false

A path is in scope when it starts with an apply_to prefix and with no skip prefix. Only prose files are rewritten: Markdown and plain text. Generated data (.json, .ics, .yaml, .csv) never is, even in scope. workload/, raw/, templates/ and wiki/ are never in scope, whatever the settings say.

Step 1 — Decide whether to run

Run when either is true:

  • another skill is about to write a file whose path is in scope (the AGENTS.md module block sends it here), or the chat answer is about to go out and chat: true;
  • the user asks directly ("rewrite this in our voice", "use the Feynman voice", "make this less AI") — then scope and mode don't matter.

Then by mode:

  • off → write the draft unchanged. Say nothing.
  • ask → ask once per file: "Write <path> in the <profile> voice?" A no writes the draft unchanged.
  • auto → continue.

Step 2 — Resolve the profile

First match wins:

  1. a profile named in the request ("in the Feynman voice", "use the board voice");
  2. voice: in the frontmatter of the session person's workload/profiles/<author-slug>.md;
  3. profile in the settings.

Read wiki/voice/<name>.md. If it doesn't exist:

  • On an automatic run, write the draft unchanged and say once per session: "(No <name> voice profile yet, so <path> went out as drafted. Say 'calibrate the voice' to create one.)"
  • On a direct request, list wiki/voice/index.md and ask which to use, or offer to calibrate one.

A profile with review: needs_update is still used; mention it once. A profile marked superseded_by is replaced by its successor.

Say which voice you used in one line, e.g. "(Written in the house voice.)" Never mix two profiles in one text.

Step 3 — Freeze what must not change

Before touching anything, mark these spans as frozen. They come out byte-for-byte as they went in:

  • frontmatter, then add or update only voice: <name> in it;
  • ## Sources, ## Crux and every blockquote, and each attribution line (— \path`, under "X"`), em-dash included;
  • ## Notes and ## Rules;
  • > CONTRADICTION: markers and <private> spans;
  • code blocks, inline code, file paths, URLs, links and [[wikilinks]];
  • numbers, dates, amounts, names of people, products and organisations;
  • tables of data (cell wording may be tidied, values never);
  • in a ckb-document output, the template's headings and their order.

If the voice would need a frozen span changed (a quote that breaks the rhythm, a heading in the wrong register), leave it and move on.

Step 4 — Rewrite the rest

If writer names another skill (for example a personal ghost-writer installed in the user's home directory), load it and let it do the rewrite. Pass it the profile page as its style profile and the frozen spans from Step 3 as text it must not change. Then check its output against Step 5. If it isn't available, say so once and fall back to ckb-voice.

Otherwise apply references/rules.md, with the profile overriding its defaults:

  • Tone, Formality and Sentence style replace the rules' defaults (an em-dash rate set there overrides the rules' dash advice).
  • Keep words survive even if the rules ban them; Avoid words are added to the ban list.
  • Sample paragraphs are the voice reference: match their rhythm, not their content.
  • Audience and Opinions set how much to explain and how hard to land a point.

A rewrite changes wording, order inside a paragraph and paragraph breaks. It never adds a claim, a number or an example that wasn't in the draft, and never drops one. A vague claim the rules would cut is kept and listed in the change note instead. In a KB its source may say more, and that is the author's call, not the voice's.

For a long text (about 1,500 words or more), also read references/ai-signs.md and references/good-writing.md.

Step 5 — Check, then write

Compare the rewrite with the draft before writing it:

  • every frozen span is identical (diff them, don't eyeball them);
  • every number, name, path and link in the draft is still there;
  • the headings are the same (a ckb-document output) or no fewer (anything else).

A failed check means the rewrite is wrong: fix it, or write the draft unchanged and say why. Then write the file and add one line to the reply: "Voice: <name>. Main change: ." On a direct request with no file, return the text and the same line.

The written file is the calling skill's output. Its log and workload entries are that skill's, and this skill adds none.

Maintaining profiles

A profile page

wiki/voice/<name>.md, one per voice. The name is a lower-case slug (house, board, michal-kopec, feynman). Write it from references/profile-template.md:

---
type: voice-profile
tldr: <who this voice is for and what it sounds like, one sentence>
voice_of: team | person | third-party   # whose voice it is
last_updated: YYYY-MM-DD
retention: high
review: draft
---

The body has the sections in the template: Tone, Formality, Sentence style, Keep, Avoid, Audience, Opinions, Sample, then the reserved ## Sources (documents the voice was calibrated from, fingerprinted as AGENTS.md §2 says) and ## Notes (protected).

wiki/voice/index.md lists every profile with its tldr, and wiki/index.md routes to it. Create both with the first profile. Every create or change under wiki/voice/ is logged in wiki/log.md (Rule B) before going further.

A profile is knowledge about how to write. It is not evidence for any other claim, and ckb-retrieve should not ground a factual answer on it.

Calibrate ("calibrate our writing style", "create a voice profile for X")

Run references/calibration.md. It asks for sample documents first and then at most four short questions, one at a time, and writes the page with review: draft. Sample documents the user points to inside the KB (raw/archive/, outputs/) are cited in ## Sources. Files from elsewhere go to raw/inbox/ first, and only on a yes, so they can be fingerprinted. A third-party voice (a writer, a public figure) is built from published text and marked voice_of: third-party; its Sample holds a few lines at most, never whole passages.

Update one thing ("we never say 'leverage'", "the board voice is more formal")

A standing preference, said during any work, goes to the profile in use: change only the field it touches, set last_updated, set review: needs_update on a reviewed page, log it, and confirm in one line. "Make this one more formal" is a one-off. Apply it and don't save it. If it's unclear which, ask: "Keep that for future texts, or just this one?"

Never write a preference learned for one profile into another.

Personal default ("use my own voice by default")

Write voice: <name> into the frontmatter of the person's workload/profiles/<author-slug>.md, creating the profile through ckb-profile if it doesn't exist. It changes their sessions only.

List ("list voices", "what voices do we have")

Show wiki/voice/index.md: name, voice_of, tldr, review state, and mark the default and the current person's choice.

Retire

Never delete a profile on a request to change it. A replaced voice gets superseded_by, and its successor gets supersedes. Delete only on an explicit "delete the X voice", logged.

Changing the settings

"Set the voice mode to ask", "turn the voice off", "make board the default voice", "also apply the voice to outputs/teaching/", "rewrite chat answers too". Edit only the config: of the voice entry in ckb.yaml, keeping everything else in the file intact, and confirm the new value in one line. Refuse an apply_to under wiki/, raw/, workload/ or templates/ and say why: the wiki stays plain, raw material and workload notes are records, and templates are the user's.

What this skill does not do

  • It does not check facts or add knowledge. Content goes out as the calling skill drafted it.
  • It does not rewrite wiki pages, quotes or code.
  • It does not change the language (English/Polish, British/American) unless the profile or the request says so.