SKILL.md

Drop-in skill that teaches a coding agent to draft, preview, and publish to Floggy with the CMS SDK and the CLI.

Grab this skill

Drop it into .claude/skills/floggy/SKILL.md.

Open raw (.md)

A ready-made skill that teaches a coding agent (Claude Code, Codex, Cursor, and friends) how to publish to and read from a Floggy blog with the @floggy/cms library and the floggy CLI. Install it once and your agent knows how to draft a post, preview it, publish it once you approve, upload media, curate a portfolio, manage profile sections, switch the blog theme, pull your content into a site, and drive Agent Collections as a headless content store.

Install this skill

Skills live in a skills/<name>/ folder under your agent's config directory, each with its own SKILL.md. Create one for Floggy:

# Claude Code / Claude agents
mkdir -p ~/.claude/skills/floggy

# Other agents (adjust the config dir to your tool, e.g. ~/.agents)
mkdir -p ~/.agents/skills/floggy

Then click Copy skill above and paste into a new SKILL.md inside that folder:

~/.claude/skills/floggy/
└── SKILL.md

That is it. Your agent loads it as the floggy skill on the next run. Prefer a project-local skill? Put the same folder under your repo's .claude/skills/floggy/ instead.

What the skill teaches

  • @floggy/cms - a thin, fully typed library that reads your published content (posts, tags, SEO, feeds) into any site and, since 0.4.0, writes it too: create a draft, preview it, publish it. This is what an agent running on a server uses.
  • floggy CLI - the same publishing plus everything the library does not cover (uploads, notes, tasks, portfolio, profile sections, theme) from a terminal or CI. Read commands support --json for piping.
  • Which one to reach for - library when it is writing code, CLI when it is running commands.
  • Where to look things up - it points the agent at the machine-readable docs below so it fetches exact commands instead of guessing.

Every action is scoped by an API key you create in the dashboard (Settings > Developer), so a key only ever has the access you grant it.

To embed a GitHub repository as a live card in a post, put the bare repo URL (https://github.com/owner/repo) alone on its own line in the post body. Do not put other text on that line. Sub-paths (issues, tree, blob) and inline URLs render as plain links.

Draft, preview, publish

The part worth knowing about before you install it: the skill tells the agent never to publish on its own.

posts.create({ title, content }) defaults to status: "draft", so an agent writing a post puts it nowhere. Your site then serves it at /drafts/<slug> from posts.draft(slug), server-side, with the key never leaving the server. That is a plain URL you can open, or paste to whoever needs to sign off, with no login in between. Only after that does the agent call posts.publish(id), which makes the post live and fires the post.published webhook so your frontend cache expires in seconds.

The skill also carries the four rules that keep a preview route from becoming a leak: noindex, nofollow on every response, Disallow: /drafts in robots.txt, absent from the sitemap, linked from nowhere.

Collection entries work the same way, so one agent can write landing pages and blog posts, preview both at the same URL, and publish both on approval. The full walkthrough, including a copy-pasteable preview route, is in Programmatic content.

Portfolio, sections, and theme

New in @floggy/cli 0.3.0. Every command here reads with the profile:read scope and writes with profile:write on the API key. A 403 response names the scope it is missing.

Portfolio - your blog projects. Note the command is floggy portfolio, not floggy projects (that one is task projects).

  • portfolio list, create, edit <id>, delete <id>, reorder <ids...>, and portfolio page to set the projects page title and description.
  • create / edit take --name, --description, --logo <url>, --blog-url <url>, --project-url <url>, --tags a,b,c, and --visible true|false. On edit, passing an empty string clears a field. reorder wants the full ordered list of ids.
  • Two links per project. --blog-url accepts a bare post slug (my-post becomes root-relative /my-post), a /-path, or a full URL; --project-url accepts a bare domain (auto https://) or a full URL. On the blog, both links open a modal (Read blog / View project), one link navigates directly, and none makes the card non-clickable.

Sections - the sections on your profile.

  • sections list, create, edit, delete, reorder.
  • Items live under a section: sections item-add <sectionId>, item-edit <sectionId> <itemId>, item-delete <sectionId> <itemId>, item-reorder <sectionId> <itemIds...>, with --title, --description, --image, --url, --date, --end-date, --company, --location.
  • Gotcha: a section item --url is stored verbatim, with no https:// auto-prefix (unlike portfolio links), so pass a full URL.

Theme - the blog's active theme.

  • theme show, theme list, theme set <name>. Ids: floggy, void, snow (Pro), lpconkz / shishiru (premium), memento. Pro and premium themes need the matching entitlement, otherwise the API returns 403.

Agent Collections

New in @floggy/cli 0.4.0 and @floggy/cms 0.2.0. Collections are headless-only, schema-driven content stores: they never render on your Floggy blog and exist purely for external sites and automation (SEO engines, AI agents, localization pipelines) to read and write through the API. Every write creates a version, and labels act like git branch pointers - promoting a version to the production label is publishing. Pro feature; keys need the collections:read / collections:write / collections:delete scopes.

  • collections list, create <slug> --schema <file.json>, show, delete.
  • Entries: collections entries <collection>, get, set --file <entry.json>, rm.
  • Publishing and A/B: collections promote <collection> <entry> <version>, label / unlabel for arbitrary variant pointers with --meta passthrough for your analytics tool.
  • Sync: collections pull <collection> <dir> (one JSON file per entry), push (upsert with conflict detection), diff (exit 1 on drift, CI-friendly).

Read the Collections docs for schemas, the REST API, versioning, and A/B testing recipes.

Machine-readable docs

Feed these to any agent for full context. Every docs page is also available as raw markdown by appending .md to its URL.

Where to go deeper