peter/daybook
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Review and correct SKILL.md for accuracy and completeness

Browse source 
Found six real flags with zero mention anywhere in the doc:
--source-type, --source-name, --source-id, --source-prompt, --meta-json,
--dry-run. Added a new "Source & Provenance Fields" section for the
source-* flags and covered the rest inline/in Rules.

Fixed:
- html_full's cheat-sheet entry overstated the requirement as needing
  doctype/html/head/body; the actual check only requires <html>.
- The "Images Inside Content" section had grown to cover four unrelated
  topics (images, CSV/JSON, xlsx, code-as-markdown) under a header
  describing only the first one. Split into properly-titled sections:
  Images Inside Content, CSV/JSON/Spreadsheets, Other Code.
- An unclosed parenthesis in the xlsx limitations paragraph, rewritten as
  a bulleted list for clarity while fixing it.
- Nothing anywhere mentioned that this script only creates artifacts -
  update/delete need the raw API, sharing is feed-UI-only with no API
  path at all. Added an explicit scope note.
- --source-name's actual default (the resolved source, which can come
  from DAYBOOK_SOURCE, not just --source) was previously undocumented
  entirely, so "same as --source" would have been imprecise once added.

Added: available --theme values (report/tasks/base) and which kinds
ignore it, and a note that markdown/html_fragment tables now render
styled automatically (from this session's earlier CSS pass).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
peter 2026-09-02 16:42:15 +01:00
parent 4b5ec09ae2
commit d2d970f33d
1 changed files with 54 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

66
skills/daybook-posting/SKILL.md
View file

@ -41,15 +41,25 @@ DAYBOOK_SOURCE=agent
| Kind | Use for | Content shape |
|---|---|---|
| `markdown` | Reports, briefs, notes | Markdown text. Fenced code blocks get syntax highlighting. |
| `html_fragment` | Themed HTML reports/cards/tables | Body-only HTML. No `html/head/body`. |
| `html_full` | Complete custom pages/frameworks | Full HTML document with doctype/html/head/body. See "CDN Snippets" below. |
| `markdown` | Reports, briefs, notes | Markdown text. Fenced code blocks get syntax highlighting; tables (pipe syntax) render styled automatically. |
| `html_fragment` | Themed HTML reports/cards/tables | Body-only HTML. No `html/head/body`. Tables render styled automatically, same as markdown. |
| `html_full` | Complete custom pages/frameworks | Full HTML document containing `<html>` (`<!doctype>` recommended, not required). See "CDN Snippets" below. |
| `deck` | Simple slide-like artifact | Top-level `<section>...</section>` blocks. |
| `json` | Structured data, metrics, run summaries | Valid JSON text. Renders as a collapsible tree. |
| `csv` | Tabular data | CSV text, first row as header. Renders as a sortable/searchable table. |
| `csv` | Tabular data | CSV text, first row as header. Renders as a sortable/searchable table. `.xlsx` files convert to this automatically — see below. |
For images, PDFs, SVGs, and other files, use `--file`; the helper infers multipart and content type.
`--theme` (for `markdown`/`html_fragment` only) accepts `report` (default —
serif, warm background), `tasks`, or `base` (minimal, no color styling).
`deck`/`html_full`/`json`/`csv` ignore `--theme` — each has its own fixed
presentation.
This script only **creates** artifacts — none of the following are
possible through it. Updating an existing artifact's title/tags/metadata,
or deleting one, requires the raw API (see `docs/api.md`); enabling its
public share link is feed-UI-only, with no API equivalent at all yet.
## CDN Snippets For `html_full`
`html_full` is Daybook's escape hatch for custom pages — nothing is
@ -111,6 +121,8 @@ python skills/daybook-posting/scripts/daybook_post.py report.md
The image is linked to the artifact that references it and is deleted along with it.
Unreferenced uploads are cleaned up after 24 hours.
## CSV, JSON, And Spreadsheets
For CSV and JSON, use `--kind csv`/`--kind json` with `--content-file` — or
just post the file positionally; auto-mode detects `.csv`/`.json` and picks
the right kind automatically:
@ -127,15 +139,44 @@ python skills/daybook-posting/scripts/daybook_post.py --kind json --title "Run S
python skills/daybook-posting/scripts/daybook_post.py balance_sheet.xlsx
```
The server converts it to a `csv` artifact automatically (active sheet
only; see `docs/api.md` for the full list of conversion limitations —
notably, formulas need to have been calculated by real spreadsheet software
that saved the file, and rich formatting like bold/colors/merged cells
isn't preserved).
The server converts it to a `csv` artifact automatically. Known
limitations (see `docs/api.md` for the full list):
For other code that should render today, use `--file path --as-markdown` to
post it as a Markdown fenced code block. Without `--as-markdown`, it uploads
as a downloadable binary file.
- Only the workbook's **active sheet** converts; other sheets are dropped.
- Formula cells need to have been calculated and saved by real spreadsheet
software (Excel, LibreOffice, etc.) — a workbook a script wrote but never
opened in a real spreadsheet app will show those cells blank.
- Rich formatting (bold, colors, merged cells) isn't preserved — it's a
plain sortable/searchable table either way.
- Legacy `.xls` isn't supported, only `.xlsx`.
## Other Code
For code that isn't CSV/JSON but should render today rather than download
as a binary, use `--file path --as-markdown` to wrap it in a Markdown
fenced code block (still gets syntax highlighting):
```bash
python skills/daybook-posting/scripts/daybook_post.py --file script.py --as-markdown --title "Generated Script"
```
Without `--as-markdown`, it uploads as a downloadable binary file instead.
## Source & Provenance Fields
All optional, all default to something reasonable if omitted:
| Flag | Default | Notes |
|---|---|---|
| `--source-type` | `agent` | One of `agent`, `person`, `system`. |
| `--source-name` | Same as the effective source (`--source`, or `DAYBOOK_SOURCE` if `--source` wasn't given) | Human-readable name, e.g. "Hermes Agent". |
| `--source-id` | Empty string | A stable external ID, if the poster has one. |
| `--source-prompt` | Empty string | The prompt/instruction that produced this artifact — useful for later tracing why something was posted. |
Use `--meta key=value` (repeatable) or `--meta-json '{"key": "value"}'`
(merged together if both are given) for structured, machine-readable
context like `run_id` or `model` — these end up in the artifact's
`metadata` field, distinct from tags.
## Rules
@ -144,3 +185,4 @@ as a downloadable binary file.
- Use `--tags a,b,c` for filtering.
- Use `--meta run_id=... --meta model=...` for machine-readable context.
- Never inline multiline content into the shell command; use a file or stdin.
- Add `--dry-run` to see exactly what would be sent (method, headers, payload) without actually posting — useful when unsure a payload is well-formed.