Agent skills

The papermark CLI tarball ships two manifests so AI clients can auto-discover what the CLI can do without you having to teach them:

SKILL.md — Anthropic Skill format. Read by Claude Desktop and Claude Code when the CLI is installed.
openai.yaml — OpenAI App / Action manifest. Used by ChatGPT Apps that want to invoke the CLI on the user's behalf.

Both describe the same surface. The CLI itself is the runtime — neither manifest contains executable code.

What's exposed

Both manifests expose the scripting subset of the CLI — the commands an agent can usefully invoke without surprise side effects:

Command	What an agent uses it for
`papermark doctor`	Verify auth before doing real work
`papermark documents list`	"What's in my Papermark?"
`papermark documents search <query>`	"Find me the doc named …"
`papermark documents upload <file>`	"Upload this PDF"
`papermark links create`	"Share this with a password and 7-day expiry"
`papermark views list --link <id>`	"Who looked at the deck this week?"

Destructive operations (documents delete, links delete, logout) are intentionally not in the manifests. An agent that needs to delete should do it through the regular CLI surface so the user sees the request explicitly.

Workflows the Skill encodes

SKILL.md includes three named workflows the model can latch onto:

Share a document as a protected link — search/upload, then create a link with the right protections
Answer "who viewed X" — resolve doc or link by name, then list views with analytics
Create a dataroom — verify auth, then create with optional name/description

Each workflow is a short paragraph that tells the model which commands to run in what order — not a transcript. The model interpolates the actual arguments from the user's prompt.

Auto-discovery

Claude Desktop / Claude Code

Both clients scan installed npm packages for an @anthropic-skills field or a skills/ directory in the package root. When the CLI is globally installed (npm i -g papermark), the client picks up skills/papermark/SKILL.md automatically. No config file, no manual registration.

If discovery isn't working, check:

npm list -g --depth=0 | grep papermark

ChatGPT Apps

Apps reference the manifest by URL. When the CLI is published to npm, openai.yaml is mirrored to a stable URL the App can point at. The App handles auth (user_http with bearer tokens — the user runs papermark login once on their machine) and dispatches each operation as a CLI invocation.

When to use Skills vs MCP

Both let an agent control Papermark. Pick one:

	Skills	MCP
Where it runs	The user's local CLI	A Node process the agent talks to
Best for	Rich CLI workflows, multi-step shell commands	Pure data access, multiple agents sharing state
Auth	Whatever the CLI uses (env var, config file, OAuth)	`PAPERMARK_TOKEN` env in the MCP process
Discovery	Auto when the CLI is installed	Explicit MCP client config
Side effects an agent can take	Curated subset (no deletes by default)	All 18 tools, including writes

For most users, both: install the CLI for ad-hoc work, install the MCP server when an agent needs to read or mutate Papermark in the flow of a longer task.

Inspecting the manifests

# In a globally installed CLI
ls $(npm root -g)/papermark/skills/papermark/
cat $(npm root -g)/papermark/openai.yaml

Or read them in the source repo: papermark-cli/skills/papermark/SKILL.md, papermark-cli/openai.yaml.