Rewrite posting skill to be location-agnostic
The skill was authored in this dev workspace, where the Daybook server, the skill, and the posting agent all share one directory — so it read as if the agent always runs from a Daybook source checkout on localhost. - State up front that you post to a running instance that may be anywhere, need no source checkout, and are tied to it only via DAYBOOK_URL/TOKEN. - Drop "from the project root"; reference the bundled helper by absolute path (DAYBOOK_POST=.../this-skill/scripts/daybook_post.py). - Reframe DAYBOOK_URL as set-this-to-your-instance; label 127.0.0.1:8001 as the local dev fallback only. - Genericize the hardcoded localhost URL in the image-embed example. - Add a raw curl fallback for environments without the Python helper. - Keep frontmatter to name+description (the Skills-API-portable subset). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
parent
6859be688e
commit
caeb2bedc7
1 changed files with 90 additions and 30 deletions
|
|
@ -1,26 +1,13 @@
|
|||
---
|
||||
name: daybook-posting
|
||||
description: Use when you have produced a finished deliverable such as a report, summary, brief, diagram, generated HTML, PDF, deck, or status update that a human should review later outside this chat. Publishes the artifact to Daybook and returns a URL.
|
||||
description: Use when you have produced a finished deliverable such as a report, summary, brief, diagram, generated HTML, PDF, deck, or status update that a human should review later outside this chat. Publishes the artifact to a Daybook instance and returns a URL.
|
||||
---
|
||||
|
||||
# Daybook Posting
|
||||
|
||||
Daybook is a private artifact journal for completed agent outputs. It stores, indexes, and displays artifacts for human review. It does not execute commands, run workflows, or continue conversations.
|
||||
|
||||
Always use the helper script. Do not hand-build curl, JSON, PowerShell multipart, or inline shell content.
|
||||
|
||||
From the project root:
|
||||
|
||||
```bash
|
||||
python skills/daybook-posting/scripts/daybook_post.py --check
|
||||
python skills/daybook-posting/scripts/daybook_post.py --kind markdown --title "Build Report" --content-file report.md
|
||||
cat report.md | python skills/daybook-posting/scripts/daybook_post.py --kind markdown --title "Build Report"
|
||||
python skills/daybook-posting/scripts/daybook_post.py --file diagram.svg --title "Architecture Diagram"
|
||||
```
|
||||
|
||||
The project also keeps a compatibility wrapper at `scripts/daybook_post.py`, but the canonical helper is bundled inside this skill.
|
||||
|
||||
The artifact URL is printed as the final stdout line.
|
||||
You post to a **running Daybook server**, which may be anywhere — a cloud VM, a container, or a workstation. You do **not** need a checkout of Daybook's source. The only things that tie you to a particular instance are two environment variables: `DAYBOOK_URL` (where the server is) and `DAYBOOK_TOKEN` (who you are). Set those and the rest of this skill works unchanged regardless of where you or the server run.
|
||||
|
||||
## Configuration
|
||||
|
||||
|
|
@ -30,12 +17,54 @@ config) — the helper reads `os.environ` directly. There is no `.env` file
|
|||
support; a `.env` file in the working directory is not read automatically.
|
||||
|
||||
```text
|
||||
DAYBOOK_URL=http://127.0.0.1:8001
|
||||
DAYBOOK_TOKEN=your-personal-api-token
|
||||
DAYBOOK_SOURCE=agent
|
||||
DAYBOOK_URL=https://your-daybook-instance.example.com # your server's base URL
|
||||
DAYBOOK_TOKEN=your-personal-api-token # from Settings -> Account
|
||||
DAYBOOK_SOURCE=agent # a stable label for what's posting
|
||||
```
|
||||
|
||||
`DAYBOOK_TOKEN` is your personal per-user API token, from Settings → Account in the app (not a token shared by everyone). Artifacts posted with your token land only in your feed.
|
||||
- **`DAYBOOK_URL`** — the base URL of the Daybook instance you're posting to.
|
||||
Set it to your server. If it's unset, the helper falls back to
|
||||
`http://127.0.0.1:8001`, which is only correct when Daybook is running
|
||||
locally on the same machine (its development default). For any remote or
|
||||
deployed instance you **must** set this.
|
||||
- **`DAYBOOK_TOKEN`** — your personal per-user API token, from Settings →
|
||||
Account in the app (not a token shared by everyone). Artifacts posted with
|
||||
your token land only in your feed.
|
||||
- **`DAYBOOK_SOURCE`** — a free-text label for whatever is posting
|
||||
(agent-profile, script, or person name). Optional; can also be passed per
|
||||
call with `--source`.
|
||||
|
||||
## The Helper
|
||||
|
||||
Always use the bundled helper script. Do not hand-build curl, JSON,
|
||||
PowerShell multipart, or inline shell content (a `curl` fallback for
|
||||
environments without the helper is documented at the end — the script is
|
||||
still preferred everywhere it's available).
|
||||
|
||||
The helper lives at **`scripts/daybook_post.py` inside this skill's own
|
||||
directory** — not in any project you happen to be working in. Invoke it by
|
||||
its absolute path. For brevity, the examples below assume you've captured
|
||||
that path once:
|
||||
|
||||
```bash
|
||||
# Point this at the helper inside THIS skill directory (absolute path).
|
||||
DAYBOOK_POST=/abs/path/to/this/skill/scripts/daybook_post.py
|
||||
```
|
||||
|
||||
Then:
|
||||
|
||||
```bash
|
||||
python "$DAYBOOK_POST" --check
|
||||
python "$DAYBOOK_POST" --kind markdown --title "Build Report" --content-file report.md
|
||||
cat report.md | python "$DAYBOOK_POST" --kind markdown --title "Build Report"
|
||||
python "$DAYBOOK_POST" --file diagram.svg --title "Architecture Diagram"
|
||||
```
|
||||
|
||||
The artifact URL is printed as the final stdout line.
|
||||
|
||||
(If you *are* working inside a Daybook source checkout, a compatibility
|
||||
wrapper also exists at `scripts/daybook_post.py` in the repo root, but the
|
||||
canonical helper is the one bundled in this skill.)
|
||||
|
||||
## Kind Cheat Sheet
|
||||
|
||||
|
|
@ -65,8 +94,9 @@ 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.
|
||||
or deleting one, requires the raw API (see the instance's `docs/api.md` or
|
||||
`GET /api/capabilities`); enabling its public share link is feed-UI-only,
|
||||
with no API equivalent at all yet.
|
||||
|
||||
## CDN Snippets For `html_full`
|
||||
|
||||
|
|
@ -119,11 +149,12 @@ artifact), upload it first and reference the returned URL:
|
|||
|
||||
```bash
|
||||
# 1. Upload -> prints the URL as the last line
|
||||
python skills/daybook-posting/scripts/daybook_post.py --upload-image chart.png
|
||||
python "$DAYBOOK_POST" --upload-image chart.png
|
||||
|
||||
# 2. Reference that URL in your markdown, then post as usual
|
||||
# 
|
||||
python skills/daybook-posting/scripts/daybook_post.py report.md
|
||||
# 2. Reference that URL in your markdown, then post as usual.
|
||||
# The printed URL is absolute against your DAYBOOK_URL, e.g.
|
||||
# 
|
||||
python "$DAYBOOK_POST" report.md
|
||||
```
|
||||
|
||||
The image is linked to the artifact that references it and is deleted along with it.
|
||||
|
|
@ -136,19 +167,19 @@ just post the file positionally; auto-mode detects `.csv`/`.json` and picks
|
|||
the right kind automatically:
|
||||
|
||||
```bash
|
||||
python skills/daybook-posting/scripts/daybook_post.py results.csv
|
||||
python skills/daybook-posting/scripts/daybook_post.py --kind json --title "Run Summary" --content-file summary.json
|
||||
python "$DAYBOOK_POST" results.csv
|
||||
python "$DAYBOOK_POST" --kind json --title "Run Summary" --content-file summary.json
|
||||
```
|
||||
|
||||
`.xlsx` spreadsheets work too, with no special flag needed — just `--file`
|
||||
(or post it positionally, same as any other file):
|
||||
|
||||
```bash
|
||||
python skills/daybook-posting/scripts/daybook_post.py balance_sheet.xlsx
|
||||
python "$DAYBOOK_POST" balance_sheet.xlsx
|
||||
```
|
||||
|
||||
The server converts it to a `csv` artifact automatically. Known
|
||||
limitations (see `docs/api.md` for the full list):
|
||||
limitations (see the instance's `docs/api.md` for the full list):
|
||||
|
||||
- Only the workbook's **active sheet** converts; other sheets are dropped.
|
||||
- Formula cells need to have been calculated and saved by real spreadsheet
|
||||
|
|
@ -165,7 +196,7 @@ 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"
|
||||
python "$DAYBOOK_POST" --file script.py --as-markdown --title "Generated Script"
|
||||
```
|
||||
|
||||
Without `--as-markdown`, it uploads as a downloadable binary file instead.
|
||||
|
|
@ -189,8 +220,37 @@ context like `run_id` or `model` — these end up in the artifact's
|
|||
## Rules
|
||||
|
||||
- Run `--check` first if unsure Daybook is reachable.
|
||||
- Make sure `DAYBOOK_URL` points at the right instance and `DAYBOOK_TOKEN` is set before posting anything real.
|
||||
- Use a stable `DAYBOOK_SOURCE` or pass `--source` (the agent-profile, script, or person name that produced this artifact).
|
||||
- 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.
|
||||
|
||||
## `curl` Fallback (No Helper Available)
|
||||
|
||||
Prefer the helper above — it handles multipart, content-type inference,
|
||||
JSON shaping, and provenance flags for you. Use raw `curl` **only** when you
|
||||
genuinely can't run the bundled Python script (e.g. a minimal environment
|
||||
with no Python). Text artifacts post as JSON to `POST /api/artifacts` with
|
||||
bearer-token auth:
|
||||
|
||||
```bash
|
||||
curl -sS -X POST "$DAYBOOK_URL/api/artifacts" \
|
||||
-H "Authorization: Bearer $DAYBOOK_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"kind":"markdown","title":"Build Report","source":"agent","content":"# Hello\n\nBody text."}'
|
||||
```
|
||||
|
||||
File/image artifacts use multipart instead:
|
||||
|
||||
```bash
|
||||
curl -sS -X POST "$DAYBOOK_URL/api/artifacts" \
|
||||
-H "Authorization: Bearer $DAYBOOK_TOKEN" \
|
||||
-F "kind=image" -F "title=Architecture Diagram" -F "source=agent" \
|
||||
-F "file=@diagram.png"
|
||||
```
|
||||
|
||||
`GET $DAYBOOK_URL/api/capabilities` (no auth needed beyond a login/token per
|
||||
that instance's config) lists supported kinds, methods, and the server
|
||||
version if you need to confirm the contract before posting.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue