# Ki Authoring

> Lead the Authoring guild and govern KI document formats, Markdown, TOML, README composition, industry white papers, and durable knowledge placement. Use to format or audit authored documents, shape a README, decide where learning belongs, or find the skill for decision records, diagrams, specifications or guides; use `ki-skills` for SKILL.md quality, `ki-repo` for repository contracts, and `ki-engineering` for code toolchains.

- Skill: `knowledgeislands/ki-authoring-2` (Agent Skill, multi-file: 24 files)
- Install (CLI): `npx get-skill add knowledgeislands/ki-authoring-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/knowledgeislands/ki-authoring-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: knowledgeislands (https://skillmd.com/u/knowledgeislands)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/knowledgeislands/ki-authoring-2

---


# Knowledge Islands authoring conventions

You are applying the **Knowledge Islands authoring conventions** — the foundational authoring and formatting rules every other skill, repository, and base in this work builds on rather than restates. Conventions are a common theme across the skill set; this skill is the one place they live, so the rest can assume them. It is the **single source of truth**: a repository's always-loaded orientation carries a one-line pointer here instead of restating the rules, keeping that standing context small and the detail in one versioned place.

This is a **standard, base-agnostic governance skill** — it hard-codes no single base and assumes no knowledge-base structure. Install it anywhere the conventions should apply. How it sits alongside the other skills in this repository, and where it must not overlap them, is documented once in the ki-agent-backpack `README.md`, not repeated here.

## The Authoring guild

This skill leads the Authoring guild: documents and writing things down. It holds the formats and how things are written; each member owns one kind of record a repository keeps:

- **`ki-decision-records`** for the why: typed decision records, their rationale and authority.
- **`ki-specs`** for accepted behaviour: specifications with their conformance state, verification plans and evidence.
- **`ki-guides`** for the practical how: guides to using, operating, contributing to or maintaining a system.
- **`ki-diagrams`** for living diagrams that explain a system, kept fresh beside their sources.

## Document formats come first

Every standard, change document and sources file follows the format standard for its type, and every format standard follows the [format format](references/standard-formats-format.md): the [standard](references/standard-formats-standard.md), [change document](references/standard-formats-change.md) and [sources file](references/standard-formats-sources.md) formats. These formats are the baseline the other conventions build on; a document is written to its format before anything else here applies. AUDIT reports a document that does not follow its format, or follows an older version of it, and CONFORM brings it into line when it is next changed.

## The two layers

A convention is one of two kinds, and the distinction decides where it lives — never restate a mechanically-enforced rule here:

- **Mechanical** — deterministically enforced by the house toolchain, so you never hand-apply it. This skill **owns `.editorconfig` and `.rumdl.toml` wholly** (SHAPE-16 `owns:`); how AUDIT and CONFORM treat them, the `owned_file_exceptions` safety valve and the retired Prettier and markdownlint configuration are set in the [Authoring enforcement](references/standard-authoring.md#41-owned-configuration) standard. **rumdl** owns authored Markdown, formatting and linting it in one pass (prose wrapping, bullet/quote characters, heading hierarchy, single H1, spacing); run `ki repo audit --skill ki-authoring` / `ki repo conform --skill ki-authoring`. **Biome** owns TS/JSON. Nothing in the toolchain formats **TOML** or aligns a Markdown table, so those conventions are entirely the judgment layer below.
- **Judgment** — needs a person or model deciding: when a wide table should spill into footnotes, whether link text is descriptive, and whether existing TOML values and comments read clearly. The toolchain cannot assess these. **This is what this skill carries.**

So the workflow when authoring or tidying Markdown is: write to the judgment conventions, then run `ki repo conform --skill ki-authoring` to settle everything mechanical. TOML has no such mechanical pass: apply its presentation conventions without renaming keys or changing table structure; route those semantic questions to `ki-repo`.

## Operating modes

Like every governance skill it carries the universal **AUDIT · CONFORM · EDUCATE · REFRESH**; EDUCATE scaffolds no artifact of its own. Invoked as `help` / `-h` / `?`, it explains itself and stops — the generated HELP block (name, purpose, invocation, modes, off-ramps), taking no action. With no mode it does the same, then, in an interactive session only, offers the mode choice via `AskUserQuestion`, prompting for any `argument-hint` target the chosen mode shows. The conventions each mode acts on are the **Convention sets** below; the checkable criteria are in [the rubric](references/rubric.md).

### Mode AUDIT — check a document against house style

1. **Run the hosted structured checker** — `ki repo audit --skill ki-authoring --repo <repo-path>`. The catalogue prepares the formatter evidence with shell-free argument arrays, so the check is self-sufficient in a repository with or without `ki-engineering` or a `package.json`. The host owns findings, reporting, and the non-zero exit on any FAIL.
2. Apply the **judgment** (`[J]`) criteria from [the rubric](references/rubric.md) — the response summary counts what remains unevaluated, but does not manufacture findings for review work the checker did not perform. Does a wide table spill into footnotes? Is link text descriptive? Do existing TOML values, comments, and configuration structure read clearly? Do not assess what keys or table identities mean here: `ki-repo` owns that contract.
3. **Report** by location → criterion → fix; lead with FAIL findings, then judgment findings. Trade records under `+/_TRADES/` and `-/_TRADES/` are authored Markdown like any other and are formatted with the rest. Their integrity is a property of meaning, not bytes: `ki-trades` `AUTH-1` compares a record against the sender's copy through a projection that ignores formatting, so formatting them changes nothing it checks. An exclusion list was the weaker guarantee — it only avoided touching the records, never verified them, and never covered Biome at all.

### Mode CONFORM — bring a document into house style

1. Apply judgment transforms in place — wide tables → footnotes (using the marker series), descriptive link text, and TOML value, comment, and presentation structure — following the Convention sets below. Do not rename TOML keys or change parsed table semantics.
2. Run `ki repo conform --skill ki-authoring --repo <repo-path>` to settle the mechanical layer (transient `MD052` until reference definitions land). Table alignment is **not** mechanical — no rumdl setting reproduces the former conditional padding, so keeping a table readable is judgment work. The owned-file item prepares early transactional writes; the Markdown item requests late formatter commands from the host.
3. Re-run AUDIT until the mechanical gate is clean and the judgment criteria pass.

### Mode EDUCATE — teach the conventions and their mechanical footprint

Run `ki repo educate --skill ki-authoring --repo <repo-path>` to render the registered rubric's concern and convention families. EDUCATE explains the Markdown and TOML judgment boundaries and names the two wholly owned configuration files. CONFORM, not EDUCATE, transactionally scaffolds or corrects those files and requests the Markdown normalisation commands.

### Mode REFRESH — re-anchor the conventions to their sources

**Precondition:** REFRESH edits this skill's own canonical files, which exist only in `ki-agent-backpack`. Invoked from an installed copy, it stops here and names the backpack as where to run it — or, for a pattern recurring across bases, routes it through `ki-repo-kb`'s IMPROVE mode instead.

The house conventions sit on top of external tools and specs (CommonMark, rumdl, the TOML spec), which move. Run on its declared cadence (see `references/sources.md`), or when asked "are the authoring conventions current".

1. **Read [the source list](references/sources.md)** — each tracked source with its `last reviewed` date.
2. **Re-fetch each** (WebFetch; fall back to WebSearch if a host is blocked or returns non-200) and diff against the convention references: a changed rumdl default that shifts what's mechanical, a CommonMark/TOML change, a rule worth adopting.
3. **Re-test every disabled rule** against the reproduction recorded for it under the source list's open watch-items, and re-enable the ones upstream has fixed. A rule is disabled because of a specific defect or a specific decision, never as a permanent verdict — left unexamined, a defensive setting outlives its defect and silently costs the coverage it was meant to protect. Run the reproduction rather than trusting a changelog: `MD075` corrupted files while reporting them clean, so upstream's own signal is not sufficient evidence.
4. **Propose a diff** to the convention references (and this skill); confirm before writing.
5. **Update [the source list](references/sources.md)** — bump each `last reviewed` date and refresh the `## Last review` block (what's confirmed, open watch-items). What changed goes in the commit, not a changelog.

## Convention sets

Each set is a self-contained reference, loaded on demand. Read the one relevant to what you are writing.

- **[Authoring enforcement](references/standard-authoring.md)** — wholly owned configuration, the Markdown formatter/linter gate, and the safe hosted conform boundary.
- **[Markdown authoring](references/standard-markdown.md)** — wide tables → footnotes (with the marker series), link style, and what to leave to the linter. The footnote-marker series, in order, is `†` `‡` `§` `¶` `‖` (then doubled: `††` `‡‡` `§§` `¶¶` `‖‖`), reset per table — omitting `*`, which collides with markdown emphasis; where one table needs two footnote categories, a visually distinct second series `※` `❡` `¤` `¥` separates them. (Stated here so it is reachable without opening the reference; the worked example, gotchas, and rationale stay in the reference.)
- **[TOML formatting](references/standard-toml.md)** — value quoting, short arrays, comments, neighbourhood banners, and compact dotted child keys; `ki-repo` owns key and table semantics.
- **[README composition](references/standard-readme.md)** — purpose-first entry points, proportional navigation and examples, discoverable user routes, and explicit library-template exclusions.
- **[Industry white papers](references/standard-whitepapers.md)** — reader-led argument, evidence, deployment implications, and editorial review; load when authoring or reviewing a white paper.
- **[Knowledge promotion](references/standard-knowledge-promotion.md)** — runtime-neutral placement, evidence, and reconciliation for durable learnings, and the durable document types, each with its format standard; it routes knowledge deliberately without mining transcripts or creating guide areas automatically.
- **Format standards** — what every type of document shares, in the [format format](references/standard-formats-format.md), and the format of each type: the [standard](references/standard-formats-standard.md), the [change document](references/standard-formats-change.md) (`.change.md`) and the [sources file](references/standard-formats-sources.md). Load when writing or reviewing a document of one of these types.
- **[Worked exemplars](references/exemplars.md)** — annotated illustrations of the conventions in practice: the footnote-marker series and table spill, relative-link style, and a well-formed `.ki.toml` structure. Reach for these when a rule's application is a judgment call.

Out of scope by design, with their natural homes:

- **KB note-writing conventions** (zones, frontmatter, routing) → the `ki-repo-kb` skill.
- **Commit and PR conventions, a repo's configuration, and the `.ki.toml` _contract_** (the compliance marker + one-table-per-skill model) → the `ki-repo` skill. This skill owns only the TOML _formatting_ style every such table is written in.
- **SKILL.md authoring** (frontmatter, description, body altitude) → the `ki-skills` skill.

## Adding a convention set

Keep this skill a thin router so growth has one obvious shape:

1. Add `references/standard-<topic>.md`, in the [standard format](references/standard-formats-standard.md), holding the **judgment** rules only — state each rule with its _why_, justify why the topic deserves its own standard, and name what is left to the mechanical toolchain.
2. Add one entry to the **Convention sets** list above with a one-line "covers" and the link.
3. Add the topic to the list of what the `description` governs, so the new set surfaces at selection time.

Mutually-exclusive sets stay in separate files so an unrelated set never loads. If a set has a clear off-ramp to another skill, name it in the "Out of scope" list rather than absorbing it here.

