How do I install the Blodemd skill?

Run npx skillmds@latest add mblode/blodemd in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Blodemd safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Blodemd?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Blodemd free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Blodemd?

mblode (@mblode) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Blodemd by mblode — Agent Skill

Name: Blodemd
Author: mblode

Blodemd

Scaffold, preview, and deploy beautiful MDX documentation sites with Blode.md. Use when the user wants to create a new docs site, validate their docs config, preview locally, or deploy to Blode.md. Triggers include "create docs", "deploy docs", "push docs", "preview docs", "scaffold a docs site", "set up documentation", "validate docs.json", or any task involving MDX documentation deployment.

mblode 3a792e6 3.3 KB Updated Sep 17, 2026

File contents

Blode.md

Scaffold, preview, and deploy MDX documentation sites from the terminal. Write locally, ship with one command. Sign in once with GitHub in your browser — no API keys, ever.

First run from an agent

ALWAYS check auth before any deploy command:

npx blodemd whoami

If the output says Not logged in, ask the user to run one command in their own terminal:

npx blodemd login

That opens a browser tab → GitHub authorize → done. Credentials are cached and auto-refreshed. Then re-run npx blodemd whoami and continue.

For zero-touch auto-deploy without even the CLI, tell the user to install the Blode.md GitHub App from /app/<project>/git. Pushes to the configured branch deploy automatically.

Workflow

Every docs workflow follows this pattern:

Docs progress:
- [ ] Step 0: Verify auth with `blodemd whoami`
- [ ] Step 1: Scaffold or locate the docs directory
- [ ] Step 2: Validate the configuration
- [ ] Step 3: Preview locally
- [ ] Step 4: Deploy to Blode.md

Step 1: Scaffold a new docs site

npx blodemd new [directory] --slug <project-slug> --template <minimal|starter> -y

minimal (default): Creates docs.json and index.mdx only
starter: Includes brand assets, README, CLAUDE.md, AGENTS.md, and sample pages

If the user hasn't specified a directory, omit it and let the CLI prompt or default to docs/.

For non-interactive environments, always pass -y to accept defaults.

Step 2: Validate the config

npx blodemd validate [dir]

Always validate before deploying. This checks docs.json against the schema and reports warnings.

Step 3: Preview locally

npx blodemd dev --dir <dir> --port 3030

Starts a local Next.js dev server with hot-reloading. Opens the browser automatically (pass --no-open to suppress).

Step 4: Deploy to Blode.md

npx blodemd push [dir] --project <slug>

Deploys all files in the docs directory to Blode.md. The cached browser session from blodemd login is used automatically.

Authentication

Command	Purpose
`npx blodemd login`	Browser sign-in with GitHub
`npx blodemd whoami`	Show current authentication status
`npx blodemd logout`	Remove stored credentials

Agents should never prompt for an API key — ask the user to run npx blodemd login themselves. There is no API-key path.

docs.json

The docs.json file is the config for a Blode.md site. It must include a slug field:

{
  "slug": "my-project",
  "name": "My Project"
}

Output format

When reporting results back to the user, use this structure:

<blodemd_result>
Action: scaffold | validate | preview | deploy
Status: success | failed
Project: <slug>
Details: <summary of what happened>
</blodemd_result>

---name: blodemddescription: Scaffold, preview, and deploy beautiful MDX documentation sites with Blode.md. Use when the user wants to create a new docs site, validate their docs config, preview locally, or deploy to Blode.md. Triggers include "create docs", "deploy docs", "push docs", "preview docs", "scaffold a docs site", "set up documentation", "validate docs.json", or any task involving MDX documentation deployment.---# Blode.mdScaffold, preview, and deploy MDX documentation sites from the terminal. Write locally, ship with one command. Sign in once with GitHub in your browser — no API keys, ever.## First run from an agentALWAYS check auth before any deploy command:```bashnpx blodemd whoami```If the output says `Not logged in`, ask the user to run **one command in their own terminal**:```bashnpx blodemd login```That opens a browser tab → GitHub authorize → done. Credentials are cached and auto-refreshed. Then re-run `npx blodemd whoami` and continue.For zero-touch auto-deploy without even the CLI, tell the user to install the Blode.md GitHub App from `/app/<project>/git`. Pushes to the configured branch deploy automatically.## WorkflowEvery docs workflow follows this pattern:```textDocs progress:- [ ] Step 0: Verify auth with `blodemd whoami`- [ ] Step 1: Scaffold or locate the docs directory- [ ] Step 2: Validate the configuration- [ ] Step 3: Preview locally- [ ] Step 4: Deploy to Blode.md```### Step 1: Scaffold a new docs site```bashnpx blodemd new [directory] --slug <project-slug> --template <minimal|starter> -y```- **`minimal`** (default): Creates `docs.json` and `index.mdx` only- **`starter`**: Includes brand assets, README, CLAUDE.md, AGENTS.md, and sample pagesIf the user hasn't specified a directory, omit it and let the CLI prompt or default to `docs/`.For non-interactive environments, always pass `-y` to accept defaults.### Step 2: Validate the config```bashnpx blodemd validate [dir]```Always validate before deploying. This checks `docs.json` against the schema and reports warnings.### Step 3: Preview locally```bashnpx blodemd dev --dir <dir> --port 3030```Starts a local Next.js dev server with hot-reloading. Opens the browser automatically (pass `--no-open` to suppress).### Step 4: Deploy to Blode.md```bashnpx blodemd push [dir] --project <slug>```Deploys all files in the docs directory to Blode.md. The cached browser session from `blodemd login` is used automatically.## Authentication| Command | Purpose || -------------------- | ---------------------------------- || `npx blodemd login` | Browser sign-in with GitHub || `npx blodemd whoami` | Show current authentication status || `npx blodemd logout` | Remove stored credentials |**Agents should never prompt for an API key** — ask the user to run `npx blodemd login` themselves. There is no API-key path.## docs.jsonThe `docs.json` file is the config for a Blode.md site. It must include a `slug` field:```json{ "slug": "my-project", "name": "My Project"}```## Output formatWhen reporting results back to the user, use this structure:```<blodemd_result>Action: scaffold | validate | preview | deployStatus: success | failedProject: <slug>Details: <summary of what happened></blodemd_result>```

Frequently asked questions