pirate-cms

Git-based CMS for marketing pages, managed by AI instead of a UI.

Content lives as structured JSON files in your repo. Velite validates and compiles them into a typed data layer at build time. pirate-skills by @wesoudshoorn is the brain — it handles positioning, copywriting, and tone variants. pirate-cms is the CMS — schema, validation, rendering, and page management.

Because everything is structured JSON, you can edit pages by hand, with an LLM, or let a scheduled agent generate them from marketing data.

Quick start

Prerequisites: Node.js 18+, a Next.js 15+ project with App Router, Claude Code

1. Add the skill

npx -y skills add https://github.com/kouliavtsev/pirate-cms

2. Run setup in Claude Code

/pirate-cms setup

An interactive wizard walks you through: installing dependencies, detecting your design system, creating the config, and setting up the build pipeline and routes.

3. Create your first page

/pirate-cms page "your product or topic"

This runs the pirate-skills positioning wizard, generates copy in 5 tones, and saves the page as structured JSON. Components and CSS are bootstrapped automatically on the first page.

What it generates

Every page is a JSON file in content/pages/:

{
  "meta": {
    "title": "API Monitoring for Startups",
    "description": "Ship reliable APIs without a dedicated ops team.",
    "slug": "api-monitoring",
    "route": "/api-monitoring",
    "language": "en",
    "createdAt": "2026-04-14T00:00:00Z"
  },
  "sections": [
    {
      "type": "hero",
      "variant": "with-checklist",
      "headline": "Your APIs break at 2am. Fix that.",
      "subheadline": "Catch failures before your users do.",
      "primaryCTA": { "text": "Start Monitoring", "href": "/signup" },
      "checklist": ["5-minute setup", "No code changes", "Free tier"]
    },
    {
      "type": "pain",
      "variant": "before-after",
      "headline": "What changes.",
      "before": { "headline": "Before", "points": ["Manual health checks", "Alert fatigue"] },
      "after": { "headline": "After", "points": ["Automated monitoring", "Smart alerts"] }
    },
    {
      "type": "features-grid",
      "variant": "icon-grid",
      "headline": "What you get.",
      "features": [
        { "title": "Uptime monitoring", "description": "Check every 30s.", "icon": "🟢" },
        { "title": "Error tracking", "description": "Stack traces, not status codes.", "icon": "🔍" },
        { "title": "Team alerts", "description": "Slack, PagerDuty, email.", "icon": "🔔" }
      ]
    },
    {
      "type": "faq",
      "variant": "default",
      "headline": "Will this slow down my API?",
      "faqs": [
        { "question": "Will this slow down my API?", "answer": "No. Monitoring runs externally." },
        { "question": "Do I need to change my code?", "answer": "No. Point it at your endpoints." }
      ]
    },
    {
      "type": "cta",
      "variant": "with-trust",
      "headline": "Start monitoring in 5 minutes.",
      "primaryCTA": { "text": "Create Free Account", "href": "/signup" },
      "trustBadges": ["No credit card", "Free forever tier", "SOC 2 compliant"]
    }
  ]
}

This is the entire page. Structured, readable, diffable. Velite validates it at build time and compiles it into a typed data layer (.velite/) that your code, components, or AI agents can consume.

Configuration

Setup creates pirate-cms.config.json at your project root — the single source of truth for your CMS:

{
  "theme": {
    "background": "#070e07",
    "accent": "#4ade80",
    "text": "#dff0df",
    "borderRadius": "8px",
    "fontHeading": "Barlow Condensed",
    "fontBody": "Inter"
  },
  "defaults": {
    "previewPrefix": "p",
    "language": "en",
    "primaryCTA": { "text": "Get Started", "href": "/signup" },
    "sections": ["hero", "pain", "features-grid", "faq", "cta"]
  },
  "routing": {
    "reservedRoutes": ["/admin", "/api", "/blog"]
  },
  "components": {
    "dir": "components/cms",
    "sections": {
      "hero":          { "mode": "theme" },
      "pain":          { "mode": "theme" },
      "features-grid": { "mode": "custom" },
      "faq":           { "mode": "theme" },
      "cta":           { "mode": "theme" }
    }
  },
  "pirateskills": {
    "product": "Your product name",
    "audience": "Who it's for",
    "preferredTone": 3
  }
}

• theme — Design tokens. Used to generate pp-* CSS that matches your brand. Change a color, run /pirate-cms style, done.
• defaults — New page defaults. Preview prefix, language, CTA, section order. Every /pirate-cms page starts with these.
• routing — Reserved routes that CMS pages can't shadow (your real app routes).
• components — Which sections exist in your component box and their rendering mode.
• pirateskills — Product context for content creation. Pre-fills the positioning wizard so you don't repeat yourself.

Component box

Section components are copied into your project on setup — like shadcn/ui, you own them:

components/cms/
  hero.tsx
  pain.tsx
  features-grid.tsx
  faq.tsx
  cta.tsx

Theme vs Custom mode

Each component has a rendering mode set in config:

theme — Uses pp-* CSS class hooks styled via your config's theme tokens. Change pirate-cms.config.json, run /pirate-cms style, and all themed components update. Good for fast, consistent styling.

custom — You rewrite the component HTML completely. pirate-cms only provides the typed section data. You render it your way — your markup, your classes, your structure.

Mix freely. Hero and CTA in theme mode for consistency, features-grid in custom mode for a unique layout. The JSON data is identical regardless of mode.

New sections from pirate-gallery

When a page needs a section type that's not in your component box, pirate-cms checks pirate-gallery for it and offers to add it. New pirate-skills sections flow in naturally — no forced upgrades.

Schema

A page is a PageDefinition: metadata + an array of typed sections.

interface PageDefinition {
  meta: {
    title: string
    description: string
    slug: string          // URL-safe identifier
    route?: string        // Custom URL (e.g. "/pricing")
    language?: string     // ISO code
    createdAt: string     // ISO datetime
    updatedAt?: string
  }
  sections: SectionContent[]  // Ordered array of typed sections
}

Section types

Each section has a type, a variant, and fields specific to that type:

| Type | What it does | Variants | |------|-------------|----------| | hero | The 5-second pitch — headline, subheadline, CTAs | default, with-image, with-proof, with-screenshot, with-checklist | | pain | Name the frustration — pain points or before/after | default, before-after | | features-grid | Scannable feature cards in different layouts | default, bento, icon-grid, showcase, tabs | | faq | Accordion Q&A (headline should be the #1 objection) | default | | cta | Final call to action with optional social proof | default, with-proof, with-trust |

5 of pirate-skills' 21 section types. More available via pirate-gallery.

For field-level schema details, see docs/architecture.md.

How pages render

content/pages/<slug>.json     Your JSON content
        ↓
    Velite (build time)       Validates schema, compiles to typed data
        ↓
    .velite/ data layer       Importable as #site/content by any code
        ↓
    <PageRenderer>            Maps sections to components from your box
        ↓
    theme or custom mode      pp-* CSS hooks  /  your own markup
        ↓
    Your styled page          Matches your design system

URL routing

Pages have two URLs — a preview URL and a published URL:

| State | URL | Indexed by search engines | |-------|-----|--------------------------| | Draft (default) | /p/<slug> | No (noindex) | | Published | /<custom-route> | Yes |

When you create a page with /pirate-cms page, it starts as a draft at /p/<slug>. The /p/ prefix is a preview namespace — hidden from search engines with noindex.

When you're happy with the page, run /pirate-cms publish <slug> to set a clean, SEO-friendly URL like /api-monitoring or /pricing. The published URL is the one search engines index.

Both URLs stay active — /p/<slug> for internal previewing, /<route> for the public.

Install

pirate-cms is a skills.sh skill that manages its own npm package. The skill is the interface — the package is the runtime. See Quick start above for the full install flow.

What /pirate-cms setup does:

1. Installs the pirate-cms npm package and velite
2. Checks pirate-gallery for available section components
3. Copies section components into components/cms/ (yours to customize)
4. Detects your design system (Tailwind colors, fonts)
5. Creates pirate-cms.config.json with your theme and defaults
6. Generates matching pp-* CSS
7. Creates velite config, route handlers (preview + published), tsconfig aliases
8. Patches Next.js config with the Velite build hook
9. Scaffolds an example page and verifies the build

Commands

| Command | What it produces | |---------|-----------------| | /pirate-cms setup | Config, component box, route handlers, CSS — full project wiring | | /pirate-cms page <topic> | content/pages/<slug>.json — new draft page via pirate-skills, or edits existing | | /pirate-cms publish <slug> | Sets meta.route — page goes from draft (/p/<slug>) to clean URL (/<route>) | | /pirate-cms list | Table of all pages with slug, title, section count, route | | /pirate-cms doctor | Health check — config, components, dependencies, build. Fixes issues. | | /pirate-cms style | Regenerates pp-* CSS from config theme tokens |

Creating content

With pirate-skills (AI-assisted): /pirate-cms page "your topic" runs the pirate-skills positioning wizard — page type, positioning questions, tone variants. Config pre-fills your product context so you don't repeat yourself. You pick tones, pirate-cms saves structured JSON.

By hand: Create or edit a JSON file in content/pages/ following the schema. Velite validates on next build. Good for quick edits — change a headline, swap a CTA, reorder sections.

With any LLM: The schema is simple enough that any LLM can generate or edit page JSON. The structured format means predictable, reliable edits.

Planned: Integrations

Scheduled agents that connect to marketing tools (Google Search Console, PostHog, Ahrefs), detect opportunities, and open PRs with draft pages for human review. See #16.

Credits

• pirate-skills by @wesoudshoorn — the brain for content creation. All creative work — positioning, tone variants, section outlines, copy quality — comes from pirate-skills.
• Velite — build-time content validation. Turns JSON into a typed data layer usable by components, custom code, APIs, or AI agents.
• skills.sh — skill distribution platform

License

MIT