From 26be37a6d59e2da9e3915fbb47d24338dab2839e Mon Sep 17 00:00:00 2001 From: Karol Chudzik Date: Thu, 16 Apr 2026 20:03:05 +0200 Subject: [PATCH] docs: surface MDCMS Skills Pack as the AI-agent setup path Add a dedicated agent-skills page to the docs site, link to it from the quickstart and agent-instructions pages, and call it out in the root README so agent users discover `npx skills add Blazity/mdcms` before reaching for copy-paste prompts. --- README.md | 2 ++ apps/docs/agent-instructions.mdx | 8 +++++ apps/docs/agent-skills.mdx | 52 ++++++++++++++++++++++++++++++++ apps/docs/docs.json | 1 + apps/docs/guide/quickstart.mdx | 6 ++++ 5 files changed, 69 insertions(+) create mode 100644 apps/docs/agent-skills.mdx diff --git a/README.md b/README.md index 9d1995e..341951d 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,8 @@ https://github.com/user-attachments/assets/b0778e3f-c062-4e66-bd6d-87f1dcb41789 ## Quick Start +> **Using an AI coding agent?** Run `npx skills add Blazity/mdcms` to install the [MDCMS Skills Pack](skills/README.md) — your agent will walk through the setup below for you. Supports Claude Code, Cursor, Gemini CLI, Codex, Copilot, and 40+ others via [skills.sh](https://skills.sh). + ### 1. Install packages ```bash diff --git a/apps/docs/agent-instructions.mdx b/apps/docs/agent-instructions.mdx index e04ee5b..df33deb 100644 --- a/apps/docs/agent-instructions.mdx +++ b/apps/docs/agent-instructions.mdx @@ -3,6 +3,14 @@ title: "Agent Instructions" description: "Copy-pasteable prompts for AI coding agents to set up and configure MDCMS" --- + + **Prefer installable skills?** If your agent supports + [skills.sh](https://skills.sh) (Claude Code, Cursor, Gemini CLI, Codex, + Copilot, and 40+ others), run `npx skills add Blazity/mdcms` to install the + [MDCMS Skills Pack](/agent-skills) — it walks your agent through the full + setup without copy-pasting prompts. + + Copy any of these prompts into [Claude Code](https://claude.ai/claude-code), [Codex](https://openai.com/index/codex/), or your preferred AI coding agent to automate MDCMS setup tasks hands-free. ## Full Project Setup diff --git a/apps/docs/agent-skills.mdx b/apps/docs/agent-skills.mdx new file mode 100644 index 0000000..ce94757 --- /dev/null +++ b/apps/docs/agent-skills.mdx @@ -0,0 +1,52 @@ +--- +title: "Agent Skills" +description: "Install the MDCMS Skills Pack so your AI coding agent can set up MDCMS end-to-end" +--- + +The **MDCMS Skills Pack** is an installable bundle of AI-agent skills that walks a coding agent through adding MDCMS to any React-based project — from standing up a self-hosted backend to day-to-day `pull`/`push` automation. + +If you use Claude Code, Cursor, Gemini CLI, Codex, Copilot, OpenCode, or any of the 40+ agents supported by [skills.sh](https://skills.sh), this is the fastest way to get an agent to do the setup for you. + +## Install + +```bash +# Install all nine skills into the current project +npx skills add Blazity/mdcms + +# Install globally so every project sees them +npx skills add Blazity/mdcms -g + +# Non-interactive (CI / scripted install) +npx skills add Blazity/mdcms -y +``` + +Installing the whole pack is recommended — the master skill delegates to the focused skills by slug. + +See the [skills.sh CLI reference](https://github.com/vercel-labs/skills) for `--copy`, `--skill`, `--agent`, and update/remove commands. + +## What's in the pack + +| Skill | Purpose | +| ----------------------------- | ---------------------------------------------------------------------------------------------- | +| `mdcms-setup` | **Master orchestrator.** Detects repo state and routes to the right focused skill. Start here. | +| `mdcms-self-host-setup` | Stand up the MDCMS backend via Docker Compose. Env, first boot, admin bootstrap. | +| `mdcms-brownfield-init` | Import an existing Markdown/MDX repo into MDCMS via `mdcms init --non-interactive`. | +| `mdcms-greenfield-init` | Bootstrap MDCMS in an empty repo with a scaffolded starter. | +| `mdcms-schema-refine` | Add/edit content types, fields, references; `mdcms schema sync`. | +| `mdcms-studio-embed` | Mount `` at a catch-all route inside the host app. | +| `mdcms-sdk-integration` | Fetch content with `@mdcms/sdk`; drafts vs published; SSR. | +| `mdcms-mdx-components` | Register custom MDX components so Studio preview and host SSR match. | +| `mdcms-content-sync-workflow` | Day-to-day `pull`/`push`; key rotation; CI automation. | + +## How to use it + +Once installed, start any conversation with your agent with an intent like "set up MDCMS in this project" or "add MDCMS here." The master skill (`mdcms-setup`) activates, detects whether you have a running server, existing content, and a host app, then delegates to each focused skill at the right phase. + +The full flow diagram and per-skill details live in the [pack's README on GitHub](https://github.com/Blazity/mdcms/blob/main/skills/README.md). + +## When to use skills vs. copy-paste prompts + +- **Skills pack** (this page) — recommended when you use one of the agents supported by skills.sh. Skills stay installed, are versioned, and delegate across setup phases. +- **[Copy-paste prompts](/agent-instructions)** — use when you want a one-shot paste into an agent window, don't want to install anything, or your agent isn't supported by skills.sh. + +Both paths target the same CLI contract (`mdcms init --non-interactive` and friends), so you can switch between them. diff --git a/apps/docs/docs.json b/apps/docs/docs.json index 6426056..cb38097 100644 --- a/apps/docs/docs.json +++ b/apps/docs/docs.json @@ -67,6 +67,7 @@ "guide/self-hosting", "guide/integration", "guide/concepts", + "agent-skills", "agent-instructions" ] }, diff --git a/apps/docs/guide/quickstart.mdx b/apps/docs/guide/quickstart.mdx index 0e062ed..34ee53e 100644 --- a/apps/docs/guide/quickstart.mdx +++ b/apps/docs/guide/quickstart.mdx @@ -16,6 +16,12 @@ Get MDCMS running in your own application. This guide assumes you have an MDCMS Setup](/development/setup). + + **Using an AI coding agent?** `npx skills add Blazity/mdcms` installs the + [MDCMS Skills Pack](/agent-skills) so your agent can walk through this + quickstart for you. + + ## 1. Install the CLI