feat: agent skill for zero-install publishing - #9
Open
FNDEVVE wants to merge 2 commits into
Open
Conversation
Resolves plannotator#2. Agents no longer need the npm-led install: a drop-in agent skill (skills/tot) teaches the full publish/update/remove lifecycle via curl against https://api.tot.page, and prefers the tot CLI when it is on PATH (asset scanning, checkpoint polling, ~/.tot registry). - SKILL.md: model-invoked skill, core model + CLI-or-curl route + markdown publish flow with the checkpoint gate - references/html-assets.md: workspace-first asset flow and scan rules - references/api.md: full endpoint reference, exact response shapes - README 'For AI agents' section; REPO_LAYOUT records skills/ All curl flows verified live end-to-end against api.tot.page (publish, checkpoint poll, living+frozen URLs, update, asset serve, delete), test pages removed afterwards.
Match the effective-html install pattern instead of manual cp into a skills directory.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #2.
What
Agents get a third consumption path beside
npm i -g @plannotator/totand the raw API doc: a drop-in agent skill (skills/tot/) that works with zero install.skills/tot/SKILL.md— model-invoked skill (Agent Skills format:name+ trigger-carryingdescription). Core model (raw serving, living vs frozen URLs, open pages, 1.5 MB limit), a CLI-or-curl route (command -v tot), and the markdown publish flow ending on the checkpoint gate: poll the read endpoint untilversionis non-null, then report living + frozen URLs.skills/tot/references/html-assets.md— the workspace-first flow for HTML with local refs: scan rules (which attributes count, what to skip), assets-before-document ordering, asset URL shape, update flow.skills/tot/references/api.md— full endpoint reference with exact response shapes, including two detailssite/agents.mdomits:POST /v1/workspacesnests under.workspace, andPOST /v1/workspaces/{ws}/documentsreturns the bare document (asymmetric withPOST /v1/documents).skills/totinto.claude/skills/,.cursor/skills/,~/.agents/skills/, …; skill preferstotwhen installed and falls back to curl otherwise.docs/REPO_LAYOUT.md— records the new directory.Why
Issue #2 ("Agent skills and instructions vs npm led install"): agents were forced down the npm install, or handed a raw API page. The skill resolves the either/or: npm CLI when present, plain curl otherwise — identical capability, zero install.
Verification
https://api.tot.page, end to end: markdown publish →201; checkpoint poll →versionnon-null; living URL servestext/markdown; charset=utf-8;PUTraw-body update → newversion+file_url, living URL moved; workspace-first HTML publish (workspace create → SVG assetPUT→ documentPOST) → asset servedimage/svg+xmlattot.page/{slug}/{assetPath}, page served astext/html;DELETE→204, living link404. All test pages deleted afterwards.pnpm lint/typecheck/format:check/test(41 passed) /build/verify:contractall green.Skill prose is deliberately tight (state-of-the-art practice for agent-facing docs): leading words (living, frozen, checkpoint gate, open page), checkable completion criteria per step, progressive disclosure of branch-only material into
references/, positive phrasing over prohibitions, and no restating of what the environment already answers.