/pkf-writing

name: pkf-writing
scope: common
description: Author, update, convert, validate, persist, and render PKF (`.pkf`) content through message-inline, Library Asset, or Memory Page carriers. Use for structured reports, knowledge pages, delivery cards, or any `.pkf` body. NOT for recall, memory-graph placement, or curation decisions — those belong to the `memory` skill.

pkf-writing

PKF is the workspace long-content format: sanitized HTML plus frontmatter, typed links, and controlled media/data/math/interactive elements. This skill owns PKF authoring and carrier discipline. The `memory` skill decides what to remember and where; domain workflows decide when a deliverable is required.

Choose exactly one carrier

| Carrier | Authority | Validation, persist, and readback | Reply | | --- | --- | --- | --- | | Message inline | PKF bytes delivered mechanically by `pkf_reply_inline`; the attached inline ContentBlock is durable with the message | validate the complete file BEFORE the call; the Runtime re-reads, re-validates, and attaches it for you; inspect the extracted/rendered receipt | Markdown projection is the reply text; never paste sentinel comments, never attach the .pkf as a file | | Library `.pkf` Asset | Library asset bytes + content hash/revision + scoped URI | dependency-free: host Library writer; dependency-bearing: atomic `pkf_bundle_commit`; read back authoritative root and graph | link the root asset and include a short projection | | Memory Page | Memory Page body + page revision | ask `memory` to choose/create the page; validate before its domain writer; read back the page and revision | summarize the remembered fact and canonical page |

Carrier authority is exclusive. Markdown projection is a readable derivative, never canonical authority. Never report success from local draft bytes alone. When the user asks for an article/report in chat and does not explicitly ask for a downloadable file or Memory page, choose Message inline. Do not create an attachment merely because the task workspace exposes an artifacts folder.

Message-inline delivery (pkf_reply_inline)

Deliver mechanically, never by pasting wire bytes: save the validated PKF to a file in the task scratch dir, then call `pkf_reply_inline({"path":"memo.pkf"})` exactly once and reply in Markdown projection; the Runtime attaches the ContentBlock. If validation is not green, do not deliver at all. Never paste sentinel comments into the reply; never attach the .pkf as a file; the Runtime still extracts the bytes between the two sentinels `<!-- prismer-pkf:inline:start -->` / `<!-- prismer-pkf:inline:end -->` for legacy agents that predate the tool — do not hand-write that region.

Authoring loop (all carriers)

1. choose carrier + authority → message inline | Library Asset | Memory Page
2. inspect source and refs    → copy real resolved URIs; never fabricate
3. mint + author + review     → `pkf_mint_sids` once; run the quality gate below; repair
   every error; resolve referenced assets
4. persist through owner      → `pkf_reply_inline` | Library/bundle writer | memory writer
5. readback + project         → URI/revision/hash + resolved validation; concise Markdown projection

**Never fabricate a URI.** Copy scoped `prismer://workspace/<ws>/asset/<sha256>` values from browse/resolve results. Inside one atomic bundle, reference bundle files by their bundle-relative path (e.g. `manifest="manifest.json"`, `src="data.csv"`); the Runtime normalizer computes every SHA-256 content hash, SRI and source hash, generates the harness manifest from `harnessDecl`, and rewrites those references into host-bound scoped asset URIs before the commit. Do not compute or hand-type hashes yourself — supply content (`bytesBase64` or `text`), paths, mime and usage only; a self-supplied hash is verified locally and a mismatch fails fast. Do not pass actor or workspace arguments to the commit tool; the host binds authority. If host-bound scope is unavailable, stop instead of guessing it. No base64/data-URI assets, remote scripts/fonts, or new bare `prismer://asset/<id>` references. If persistence or readback is unavailable, say so and retain a draft; never fake a revision.

Real command matrix and editing lanes

| Need | Structured/runtime | Native/Cloud CLI | | --- | --- | --- | | mint section ids | `pkf_mint_sids` | n/a | | inspect | `pkf_outline`, `pkf_search`, `pkf_read` | `cloud pkf inspect` or ordinary UTF-8 read | | edit local draft | normal file tools | `cloud pkf patch`, `cloud pkf diff` | | validate | `pkf_validate` | `cloud pkf validate` | | deliver message-inline | `pkf_reply_inline` (task scratch/workdir file path) | n/a | | persist Library Asset | host Library writer | `cloud asset upload` only when the host exposes it; require its receipt | | persist logical bundle | `pkf_bundle_commit` | one atomic root + dependency graph; require readback | | persist Memory Page | `memory_browse` → `memory_write` → `memory_load` | n/a | | project/export | host projection | `cloud pkf project`, `cloud pkf render` | | harness assets | n/a | `cloud pkf pack-harness` |

`pkf_mint_sids`/`pkf_validate`/`pkf_outline`/`pkf_search`/`pkf_read`/ `pkf_bundle_commit`/`pkf_reply_inline` are native **function-call tools** — not shell executables. Call them through the tool API with JSON arguments; never `command -v`, terminal probes, Python imports, or hand-written SID/validator replacements. The shell lane is only `cloud …`. If a required native tool and `cloud` are both unavailable, keep a draft and report the Runtime capability error.

The `.pkf` file is ordinary UTF-8. Validate the whole page after every edit; a 409/412 means re-read and re-target, never force. After persistence, read back canonical bytes/receipt and run resolved validation where supported.

Report quality floor + full-document review gate

Before `pkf_reply_inline` or any carrier persist, run this gate. A valid PKF shell can still be an unacceptable deliverable