- 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>
9.8 KiB
| 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:
- Apply a voice to a draft before it leaves the KB (Steps 1–5).
- 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.mdmodule block sends it here), or the chat answer is about to go out andchat: true; - the user asks directly ("rewrite this in our voice", "use the Feynman
voice", "make this less AI") — then scope and
modedon'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:
- a profile named in the request ("in the Feynman voice", "use the board voice");
voice:in the frontmatter of the session person'sworkload/profiles/<author-slug>.md;profilein 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.mdand 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,## Cruxand every blockquote, and each attribution line (— \path`, under "X"`), em-dash included;## Notesand## 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-documentoutput, 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-documentoutput) 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.