Draft CLI Skill

Use draft for JSON Workspace page-domain Draft operations and hosted Secret Share helpers.

Current Runtime Contract

• Prefer the saved JSON Workspace as the default page target.
• Use workspace metadata commands before page commands so you know which folder and source the CLI is using.
• Until headless storage is removed, pass the resolved workspace path with --workspace-json

for page commands that must operate on JSON Workspace data.

Workspace-First Pattern For Page Commands

For page commands such as draft page ls, draft page cat, draft page create,

draft page append, draft page replace, draft page patch, draft page annotate, and

draft page publish:

draft workspace status --json
draft workspace path --json

Use the returned active_workspace_path to anchor page commands explicitly:

draft --workspace-json <active_workspace_path> page ls --json
draft --workspace-json <active_workspace_path> page cat <page_id> --json

For an explicit folder override, anchor the command with --workspace-json:

draft --workspace-json <folder> page ls --json
draft --workspace-json <folder> page cat <page_id> --json

If the user wants that folder to become the default workspace, set it first:

draft workspace set-path <folder> --json
draft workspace status --json

Use the workspace metadata to confirm whether the CLI is operating on the saved default path or an

explicit override before you describe results back to the user.

Version Detection And Older CLI Fallback

Newer CLIs can expose workspace metadata commands such as:

draft workspace status --json
draft workspace path --json
draft workspace set-path <folder> --json

If those commands are unavailable, detect that once and fall back safely:

draft workspace --help
draft --workspace-json <folder> page ls --json

• If draft workspace --help or draft workspace status --json fails with an unknown-command

style error, assume the CLI is older.

• On older CLIs, require an explicit folder and run page commands with

draft --workspace-json ....

• If the user did not provide a folder and the CLI lacks workspace commands, ask for the JSON Workspace folder path or ask them to upgrade the CLI.

Page Commands

Prefer explicit draft page ... commands under a JSON Workspace target. In the transition period,

include --workspace-json so the command cannot accidentally hit legacy headless storage:

draft --workspace-json <folder> page ls --json
draft --workspace-json <folder> page search "phrase" --json
draft --workspace-json <folder> page cat <page_id> --json
draft --workspace-json <folder> page create "Title" --json
draft --workspace-json <folder> page append <page_id> "More content" --json
draft --workspace-json <folder> page replace <page_id> --heading "Status" "Updated body" --json
draft --workspace-json <folder> page patch <page_id> --json < change.diff
draft --workspace-json <folder> page annotate <page_id> --anchor "exact text" --note "Reviewer note" --json
draft --workspace-json <folder> page comments <page_id> --json
draft --workspace-json <folder> page comment <comment_id> <page_id> --json
draft --workspace-json <folder> page insert-image <page_id> ./image.png --json
draft --workspace-json <folder> page update-image <page_id> <local_id> --width 320 --json
draft --workspace-json <folder> page delete-image <page_id> <local_id> --json
draft --workspace-json <folder> page publish <page_id> --json

Agent-Native Read Guidance

• Prefer draft --workspace-json page cat for rendered page reads meant for

human review. The markdown surface preserves links, marks, tables, images, ordered lists, line

breaks, and custom blocks better than manual rendering from pages/*.json.

• Use draft --workspace-json page cat --json only when you need structured

block data for parsing or automation. It is larger than the markdown read surface.

• Treat raw workspace JSON files as a last resort for recovery or low-level inspection, not the

default read path.

• For discovery, prefer draft --workspace-json page search "phrase" --json when the CLI

supports it. On older CLIs without page search, use rg over workspace page files only to

discover candidate page IDs or titles, then switch back to `draft --workspace-json page

cat ` for authoritative rendered output.

Use draft --workspace-json page cat when you want the page content in plain

markdown for human review. Use --json only when you need raw structured document data for parsing

or automation.

Patch Contract

draft page patch applies unified diffs to the page body markdown only. Do not generate patches

from decorated human page cat output that includes Title:, ID:, or --- separator lines, and

do not generate patches from page cat --json block output.

Patch workflow:

draft --workspace-json <folder> page cat <page_id>
# Extract only the body markdown, build a unified diff against that body, then:
draft --workspace-json <folder> page patch <page_id> --json < change.diff
draft --workspace-json <folder> page cat <page_id> --json

Verify the patch output or follow-up page cat before running downstream commands that depend on

the edited text, such as page annotate --anchor "new text". If patch returns PATCH_MISMATCH,

reread the current page body markdown, regenerate a fresh diff against that exact body surface, and

retry.

Image Mutation Contract

draft page insert-image returns local_id. Use that returned local_id for subsequent

update-image and delete-image commands. In page cat --json compatibility output, the same

identifier is exposed as the image block id.

Top-level page aliases can still exist during compatibility windows, but agents should use the

draft page ... namespace.

Public Preview Feedback

Public Draft preview and published URLs expose review feedback through the public page surface, not

through JSON Workspace page commands. Treat the public preview or published URL as the primary

machine-readable entrypoint for public review workflows. When the task starts from a public preview

or published URL, fetch that public URL first, parse its metadata/frontmatter, then use the

returned endpoints in priority order.

This direct public-page feedback read path does not require draft, draft workspace status,

draft status, a JSON Workspace folder, a daemon, or browser pairing. Do not run

draft --workspace-json page comments --json just because the user supplied a

public URL.

Example for "read feedback from this public Draft preview URL":

1. Fetch the provided public preview or published URL.
2. Parse metadata/frontmatter and read comments_api_url and task_toggles_api_url as the P0

endpoints.

1. Fetch comments_api_url directly to read human feedback and comments.
2. Fetch task_toggles_api_url directly to read review toggle state and task decisions.
3. If source_snapshot_url is present, treat it as a P1 optional structured published-content

snapshot that helps match comments and toggles to the exact published body.

1. Summarize feedback and decision state, using source_snapshot_url only when it helps disambiguate

the published content under review.

Retrieval order for public review reads:

1. Fetch public URL.
2. Parse metadata/frontmatter.
3. Fetch comments_api_url.
4. Fetch task_toggles_api_url.
5. Optionally fetch source_snapshot_url.
6. Summarize feedback and decision state.

If JSON Workspace comment commands return empty for a page that also has a public preview/published

URL, do not conclude there is no feedback or no decisions until you have checked that public URL for

comments_api_url and task_toggles_api_url.

CLI comment commands such as draft --workspace-json page comments --json are

primarily for private or local Draft page workflows, live workspace pages, or local page

annotations. They are not the default public review path for preview or published URLs.

Write And Share Guardrail

Read-only behavior is the safe fallback. Do not run write/share commands unless the user explicitly

asks for the exact action and target.

• write commands: draft --workspace-json page create, draft --workspace-json page append, draft --workspace-json page replace, draft --workspace-json page patch, draft --workspace-json page annotate
• share commands: draft --workspace-json page publish, draft secret create

Before returning a public or shareable URL, review the command output and confirm it is the requested

artifact.

Secret Share

Secret Share commands are hosted/local-crypto helpers and do not require workspace checks,

draft status, or draft start-server.

Configure the API key:

draft auth set-key <secret-share-api-key>
draft auth status --json

Create a Secret Share:

draft secret create --file docs/brief.md --expires 1h --json

Read a Secret Share:

draft secret open '<secret_url_or_id>' --password "$DRAFT_SECRET_PASSWORD" --json

Use --password for password-protected shares. Use DRAFT_SECRET_PASSWORD only when the runtime

already provides it.

Error Handling

• Unknown draft workspace ... command: fall back to draft --workspace-json ... and

ask for the folder path when it is missing.

• Missing configured workspace path: use draft workspace set-path --json when the user

wants a default, or use draft --workspace-json ... for a one-off command.

• PAGE_NOT_FOUND: run draft --workspace-json page ls --json and retry with a valid page ID.
• PATCH_MISMATCH: reread with draft --workspace-json page cat , extract the page body markdown only, regenerate the patch against that exact body surface, and retry.
• ANCHOR_NOT_FOUND: reread the current page before annotating; do not annotate text that a failed patch did not create.
• Missing Secret Share API key: use draft auth set-key, --api-key, or DRAFT_SECRET_SHARE_API_KEY.