- 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>
7.3 KiB
| name | description |
|---|---|
| ckb-convert | Convert a Markdown file from the KB (a document from a template, a kept answer, a report, a wiki page) into Word .docx, OpenDocument .odt, PDF or HTML through pandoc, in a house style kept in templates/styles/ so fonts, sizes, colours and margins are never picked by hand; also creates, changes, checks and lists house styles, including one made from a company .docx/.dotx. Use for "convert this to Word", "give me this as a docx/PDF", "export the status report as a Word file", "make a house style with Georgia and navy headings", "use our company template for documents", "list the styles", "make PDF the default". |
Convert skill (module: convert)
Purpose
People outside the KB want a Word file or a PDF that looks like the rest of
their company's documents. pandoc does the conversion; the look comes from a
style, a reference .docx in templates/styles/<name>.docx that the
user never has to open. The Markdown stays the source: it's always kept, and
the converted file is made from it again whenever it changes.
Nothing here touches wiki/, so Rule B doesn't apply; Rule D does.
Settings
Under the convert entry of kb_modules: in ckb.yaml, config::
| Key | Default | Meaning |
|---|---|---|
style |
house |
Style used when the request names none |
format |
docx |
docx, odt, pdf or html when the request names none |
out_dir |
outputs/documents/ |
Where a file from outside outputs/ is written; a file already in outputs/ converts beside itself |
toc |
false |
Add a table of contents |
number_sections |
false |
Number the headings |
keep_links |
false |
Keep links to KB paths, which are dead in a Word file |
The request wins over a setting ("as a PDF", "with a table of contents").
"Make PDF the default" or "use the board style by default" edits only that
key's value in ckb.yaml and says so in one line.
The script
<python> .agents/skills/ckb-convert/scripts/convert.py <command> …
Resolve <python> per "Scripts and the Python Runtime" in AGENTS.md. Run it
from the KB root (or pass --root). Exit codes: 0 done, 1 refused (the
message says why), 3 a program is missing or failed.
| Command | Does |
|---|---|
doctor |
pandoc version, LibreOffice, how PDF will be made, styles present |
styles |
Lists templates/styles/ |
convert FILE --to FMT --style NAME [--toc] [--number-sections] [--keep-links] [--out PATH | --out-dir DIR] [--force] |
Converts one file |
new-style NAME [--from FILE] [settings] |
Creates a style from pandoc's default, or from a company .docx/.dotx |
edit-style NAME settings |
Changes a style |
check-style NAME |
Lists the styles pandoc uses that NAME doesn't define |
Settings: --body-font F, --heading-font F, --size PT (body text),
--heading-color RRGGBB, --paper a4|letter, --margin-cm CM.
How to run this skill
Step 1 — Check the tools once per session
Run doctor. If pandoc is missing, stop and tell the user how to install it
on their system (the error names the commands). Never install it yourself.
If LibreOffice is missing and they asked for PDF or ODT, say once that the
file won't follow the Word style and how to install LibreOffice, then go on.
Step 2 — Make sure there's a style
If the style to use exists, go to Step 3. If templates/styles/ has no style
at all, ask one question before converting:
There's no house style yet. Use a plain default (Calibri 11pt, dark-blue headings, A4), tell me fonts/colours/paper, or give me your company's Word template (.docx or .dotx)?
- Default:
new-style house --body-font Calibri --heading-font Calibri --size 11 --heading-color 1F3864 --paper a4 --margin-cm 2.5. - Their own settings: the same command with their values. A colour named in
words becomes hex ("navy" →
1F3864); a page size other than A4/Letter isn't supported, so say so and use the closer one. - A company template:
new-style house --from <file>. Report thecheck:lines it prints in plain words: a missing Heading 1 means headings will use pandoc's look, not the company's. Offer to fill only the missing ones with settings (edit-style), never to change the ones that exist.
If other styles exist but not the one named, list them and ask which to use.
Step 3 — Convert
Check that the Markdown is final first. If it was just written and the voice
module is installed, the voice pass comes before conversion.
<python> .agents/skills/ckb-convert/scripts/convert.py convert <file.md> --to <fmt> --style <style> [flags from settings]
Several files, or several formats of one file: one call each.
refused: exists— the converted file is already there. Ask once: replace it (--force) or keep both (--outwith-2before the extension). A file made earlier may have been edited in Word since.note:lines — pass them on in plain words. Apandoc:note about a missing image names the file; check the path.
What the script changes on the way, so you can explain it if asked: the
frontmatter becomes the title, author (without the e-mail) and date; the
first # Heading becomes the title when the frontmatter has none; <!-- comments --> are dropped; [[Wikilinks]] and links to KB paths become plain
text (--keep-links keeps the links); web links stay; code blocks stay as
they are. Sections such as ## Sources are content and stay. If the reader
shouldn't see them, offer a copy of the Markdown without them, and never edit
the original for that.
Step 4 — Report
One line per file: path, format, style. Add the notes that matter. For a
.docx with --toc, say the reader may have to accept "update fields" when
Word opens it. Offer nothing else.
Changing a style
"Make the headings green", "use Georgia", "switch to Letter paper":
edit-style <name> with only the settings asked for, then offer to
reconvert the last file. Ask first if the style came from the user's own
template (--from): they may want their file left as it is.
For anything the settings can't do (a logo in the header, a cover page, line
spacing, table borders), tell the user to open templates/styles/<name>.docx
in Word or LibreOffice, change the styles (not the text), and save it as
.docx. pandoc reads fonts, sizes, colours, spacing, page size, margins,
header and footer from it and ignores its text.
.odt and .css styles are optional and hand-made: NAME.odt is used for
ODT instead of going through LibreOffice, and NAME.css for HTML.
Edge cases
- The file isn't Markdown (a
.docxto turn into PDF): pandoc can't keep the look that way. Offer LibreOffice directly (soffice --headless --convert-to pdf) or the general document skills. - A wiki page is converted like any file. The output goes to
out_dir, never intowiki/. - Mermaid diagrams stay as code blocks; pandoc doesn't draw them. Say so if the file has one.
- Fonts aren't embedded in
.docx. A font the reader lacks shows as a substitute; in PDF, LibreOffice substitutes on this machine. Suggest common fonts if the user picks something rare. - A
.docm/.dotm(macros) is refused: ask for a copy saved as.docxor.dotx. - Without Python: run pandoc by hand,
pandoc <file.md> -o <out.docx> --reference-doc templates/styles/<style>.docx, and say the KB clean-up (frontmatter, wikilinks, comments) was skipped.