Write a Claude skill for driving markfluence

Add a Claude skill (a SKILL.md with the usual name/description frontmatter) that teaches Claude how to drive the markfluence CLI, so publishing/reading Confluence pages from markdown in a Claude session is turnkey rather than requiring the model to rediscover flags and conventions each time.

Status

A working skill exists as a user-local file at ~/.claude/skills/markfluence/SKILL.md and is kept current by hand. What is left here is deciding how it ships from this repo — see "Format / location" below. The original body's inventory of commands and flags is preserved below only where it is still true; most of it was rewritten, since the CLI it described no longer exists.

Why

markfluence has grown a fair bit of surface. A skill lets Claude apply it correctly without re-reading the code, and gives a consistent, low-friction UX for "publish these docs" / "pull this page down to edit."

What the skill should cover

The design rule the hand-written one arrived at: cover only what --help cannot, and point at markfluence CMD --help for everything else. Every command carries its reasoning in Long and a worked invocation in Example (enforced by TestSubcommandsDocumentThemselves), and docs/commands/ is generated from that same text, so a skill that restates flags is a third copy that drifts. #102 made the same call for the README. Concretely that leaves credentials, which operations need confirmation, and the handful of behaviours that produce a wrong action if the agent guesses.

• The command inventory, now seventeen rather than five: create, update, check, diff, page-info, space-info, read, children, find, search, user-find, user-info, attachment-list, attachment-upload, attachment-download, export, schema.
• Config & auth: CONFLUENCE_URL, CONFLUENCE_USERNAME (flag/env/.env), CONFLUENCE_TOKEN (env/.env only, never a flag), and CONFLUENCE_CLOUD_ID for a scoped token via the api.atlassian.com gateway; precedence flag > env > .env. user-info with no argument is the "which account am I?" answer, and a scoped token is the case where one command 401s while every other works — user-find needs the granular read:content-details:confluence, which #143/#168 measured as implied by nothing.
• --json, and leaning on it rather than enumerating fields. The output is schema-locked (schema/json-output/v1.json, guarded by internal/schematest) and markfluence schema prints it with no credentials and no network call, so an agent can parse structurally instead of scraping human output.
• Which commands are safe to run unprompted — everything read-only, check and schema included — and which need a dry-run-then-confirm. That split is most of the skill's value and none of it is in --help.
• Frontmatter: title, space, parent, page_id lead, then every other key alphabetically — which now includes labels (#21) and page_status (#168). page_width ∈ narrow/wide/max, and markfluence.yaml may carry space/page_width as project settings (#100) and a whole file's metadata in a pages: entry (#139), so "the frontmatter" is no longer only the block at the top of the file.
• Workflows to encode: publish a new tree; update an existing one; pull a page down to edit (export → edit → update); check a drafted file before ever touching the network; diff a file against its page to show a human what a publish would change.

Gotchas worth encoding

The ones that make an agent take the wrong action, not the ones that merely surprise it:

• diff's exit codes are diff(1)'s: 0 identical, 1 differs, 2 trouble. Exit 1 is a successful comparison, and an agent that reads it as failure will report the opposite of what happened. Its output is also split across two streams — stdout is the body patch and nothing else, stderr the frontmatter report.
• update refuses a page that moved on since the local copy was made, and that refusal is correct. It is no longer the mtime check the original body described: #149 records what each publish was derived from, so the two checks are a divergence refusal (--force overrides) and a body-unchanged skip (attachments, width and labels still run). An agent that reaches for --force on a refusal is publishing over someone else's work.
• There is no fix. It was removed in #151, and nothing writes an existing file's frontmatter back from its page. Adopting a hand-labeled or hand-resized page is page-info/read plus an edit; diff is what shows the gap.
• find's empty result is exit 0, and "no live page with this title" is not "the title is free": an archived page still reserves it, while a folder row is never a clash. The match is exact and case-insensitive, not a substring.
• page_status values are per page and per account, not per space (#168) — ask page-info PAGE, or space-info KEY for the space's list, which a non-admin may only get an approximation of. update validates the name before writing; create cannot, so a misspelled status there is a warning on a page that got created anyway.
• A space key, never a numeric space id, and never a valid PAGE. Use the --space flag children/export/find/search take, or space-info.
• parent may be a page id or a folder id, and nothing records which — opaque and interchangeable.
• Conversion is best-effort and lossy in documented ways (guarantees L5/L6), so a round trip will show differences the author did not make.
• --debug prints every retry decision with the rate-limit headers (#81), so "it seems to hang" is actionable; a rate-limited request can legitimately take minutes.

Format / location (to decide)

This is the remaining work. The current skill is a hand-maintained file in ~/.claude/skills/, which nothing in this repo ships or tests. Options, from the prior-art comment above:

• A skills/ directory in this repo.
• A .claude-plugin marketplace entry, the way pchuri/confluence-cli distributes theirs.
• A markfluence install-skill subcommand — interesting because shell completions already ship this way, generated from the CLI itself in a goreleaser before hook.
• An llms.txt at the repo root, cheap and conventional, orthogonal to the above.

Whichever ships, the drift question is the same one docs/commands/ already answers: the parts that can be generated from cobra help should be, and make docs-check's regenerate-and-diff is the pattern to copy if any of it is.

Open questions

• Does the skill assume markfluence is on PATH, or include install guidance (from source / Homebrew cask)?
• Is a repo-shipped skill tested at all? A skill that names a removed command is worse than no skill, and fix/info both went away while the hand-written one still advertised them.

Start with the current user-local ~/.claude/skills/markfluence/SKILL.md and compare its guidance with the command descriptions in docs/commands/. Decide which shipping format from the issue fits the repository, then define how it stays aligned with generated help and make docs-check. Done means the skill is shipped in the chosen location, covers the documented workflows and safety rules, and has a test or check preventing removed commands from returning.