Auto-Publish Specs to mkdshare.dev from Claude Code's Brainstorming Skill

by Philip Andersen

~ $ cat x9njKKCf.md

When you use the superpowers plugin for Claude Code, the brainstorming skill writes design specs to your local filesystem. That's fine — but it's much nicer to have specs automatically published to a shareable URL the moment they're written.

This post shows how to wire that up using Claude Code's project-local skill override feature and the mkdshare.dev MCP server.

How It Works

Claude Code resolves skills in this order:

  1. .claude/skills/<name>/SKILL.md — project-local (highest priority)
  2. Plugin skills (e.g. superpowers)
  3. Global user skills

If a project-local skill has the same name as a plugin skill, the local version wins. That means you can copy any superpowers skill into your project's .claude/skills/ directory, add whatever extra steps you want, and Claude will use your version instead.

Step 1: Connect the mkdshare MCP Server

Add the mkdshare MCP server to your Claude Code project. In your project's .claude/settings.json (or settings.local.json if you don't want it checked in):

{
  "mcpServers": {
    "mkdshare": {
      "command": "npx",
      "args": ["-y", "mkdshare-mcp"]
    }
  }
}

Then authenticate by asking Claude: "Authenticate with mkdshare" — it will walk you through Google sign-in via device auth.

Step 2: Create the Project-Local Skill Override

Copy the superpowers brainstorming skill into your project:

.claude/skills/brainstorming/SKILL.md

Then add these two additions:

In the checklist (step 6), change:

6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` and commit

to:

6. **Write design doc** — save to `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`, commit, and upload to mkdshare.dev

In the "After the Design → Documentation" section, add after the git commit step:

- Upload to mkdshare.dev using the `mcp__mkdshare__create_document` tool:
  - `title`: `[YYYY-MM-DD] <feature-name> Design`
  - `content`: full markdown content of the spec
  - `visibility`: `"login_required"`
  - `allowed_emails`: `"your@email.com"`

In the "User Review Gate", change the prompt to reference the mkdshare URL:

> "Spec written and posted to `<mkdshare-url>`. Please review it and let me know if you want to make any changes before we start writing out the implementation plan."

Step 3: Do the Same for Writing Plans (Optional)

The writing-plans skill can get the same treatment. Create .claude/skills/writing-plans/SKILL.md and update the "Save plans to" section:

**Save plans to:** mkdshare.dev using the `create_document` MCP tool with:
- `visibility: "login_required"`
- `allowed_emails: "your@email.com"`
- `title`: `[YYYY-MM-DD] <feature-name> Implementation Plan`

And update the execution handoff to include the mkdshare URL.

Step 4: Tell Claude to Use the Local Skills

In your CLAUDE.md, add:

Always invoke `brainstorming` (not `superpowers:brainstorming`) — the project-local version uploads specs to mkdshare.dev automatically.

Always invoke `writing-plans` (not `superpowers:writing-plans`) — the project-local version uploads plans to mkdshare.dev automatically.

This is important: if Claude invokes superpowers:brainstorming (the fully-qualified name), the plugin version runs instead of your local override.

Result

Now every time you brainstorm a feature:

  1. Claude collaborates with you through the design
  2. Writes the spec to docs/superpowers/specs/
  3. Commits it to git
  4. Automatically uploads it to mkdshare.dev and gives you a shareable URL
  5. Asks you to review it at that URL before moving to implementation

No copy-paste, no manual uploads. The spec is wherever you need it — in git for history, on mkdshare.dev for review.

Visibility Options

The create_document tool supports three visibility modes:

Mode Who can read
public Anyone with the link
login_required Any logged-in mkdshare user, or specific emails via allowed_emails
domain_restricted Users whose email matches allowed_domain

For internal specs, login_required with your team's emails is the right default. For public write-ups, use public.

Why Project-Local Skills?

This pattern is useful beyond mkdshare — the same approach works for:

The key insight: project-local skills let you layer project-specific behavior on top of shared plugin workflows, without forking the plugin.