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.
Why
markfluence has grown a fair bit of surface (five subcommands, frontmatter conventions, override flags, a lossy storage↔markdown converter, retry behavior). 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
- Purpose & direction: markdown → Confluence (
create/update) and Confluence → markdown (read), plus fix/info.
- Config & auth:
CONFLUENCE_URL, CONFLUENCE_USERNAME (flag/env/.env), and CONFLUENCE_TOKEN (env/.env only, never a flag); precedence flag > env > .env.
- Subcommands + key flags:
create FILE... — --space, --parent, --title (single FILE), --page-width, --persist/--no-persist; two-phase/transactional; writes coordinates back unless --no-persist.update FILE... — page_id required (frontmatter or --page-id); --title/--page-id (single FILE) and --page-width overrides; mtime skip + --force; never writes back.read ARG — id or URL; --format markdown (default, with frontmatter) vs storage.fix — reconcile frontmatter from the live page (read-only on the server).info ARG — metadata; --properties.
- Frontmatter schema & canonical order:
title, space, parent, page_id, page_width (then alphabetical); page_width ∈ narrow/wide/max.
- Workflows to encode: publish new tree; update existing; pull a page to edit (
read > page.md → edit → update); mark a section for edit with a (hidden) excerpt macro; invisible persistent comments via hidden excerpts.
- Gotchas: conversion is best-effort/lossy (CAUTION→WARNING, local image paths flattened, unknown macros pass through as raw storage);
--title renames the live page; --no-persist leaves no page_id so a later update needs --page-id.
Format / location (to decide)
- A
SKILL.md (name + one-line triggering description) — packaged where? A skills/ dir in this repo, a Claude plugin, or the user's ~/.claude/skills/.
- Keep it reference-style (commands, flags, recipes) rather than prose; link to the built binary / install steps.
Open questions
- Does the skill assume
markfluence is already installed/on PATH, or include install guidance (from source / Homebrew)?
- Scope to invocation guidance only, or also include troubleshooting (auth errors, 404/duplicate-title, rate-limit/retry behavior)?
- Keep it in sync with
--help/README — consider generating parts from the cobra help to avoid drift.
Follow-up would be the reusable GitHub Action (#29) for the CI side; this skill is the interactive-Claude side.
Add a Claude skill (a
SKILL.mdwith the usual name/description frontmatter) that teaches Claude how to drive themarkfluenceCLI, 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.Why
markfluence has grown a fair bit of surface (five subcommands, frontmatter conventions, override flags, a lossy storage↔markdown converter, retry behavior). 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
create/update) and Confluence → markdown (read), plusfix/info.CONFLUENCE_URL,CONFLUENCE_USERNAME(flag/env/.env), andCONFLUENCE_TOKEN(env/.envonly, never a flag); precedence flag > env >.env.create FILE...—--space,--parent,--title(single FILE),--page-width,--persist/--no-persist; two-phase/transactional; writes coordinates back unless--no-persist.update FILE...— page_id required (frontmatter or--page-id);--title/--page-id(single FILE) and--page-widthoverrides; mtime skip +--force; never writes back.read ARG— id or URL;--format markdown(default, with frontmatter) vsstorage.fix— reconcile frontmatter from the live page (read-only on the server).info ARG— metadata;--properties.title, space, parent, page_id, page_width(then alphabetical);page_width∈ narrow/wide/max.read > page.md→ edit →update); mark a section for edit with a (hidden) excerpt macro; invisible persistent comments via hidden excerpts.--titlerenames the live page;--no-persistleaves nopage_idso a laterupdateneeds--page-id.Format / location (to decide)
SKILL.md(name + one-line triggering description) — packaged where? Askills/dir in this repo, a Claude plugin, or the user's~/.claude/skills/.Open questions
markfluenceis already installed/on PATH, or include install guidance (from source / Homebrew)?--help/README — consider generating parts from the cobra help to avoid drift.Follow-up would be the reusable GitHub Action (#29) for the CI side; this skill is the interactive-Claude side.