Upload folder using huggingface_hub

.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "opendesign",
+  "description": "Open-source, skills-based version of Claude Design (claude.ai/design) for Claude Code. HTML pages, slide decks, interactive prototypes, UI kits, and brand systems.",
+  "owner": {
+    "name": "manalkaff",
+    "email": "manalkaff@gmail.com"
+  },
+  "plugins": [
+    {
+      "name": "opendesign",
+      "description": "Open-source, skills-based version of Claude Design (claude.ai/design) for Claude Code. HTML pages, slide decks, interactive prototypes, UI kits, and brand systems — with taste, context-matching, and anti-slop discipline.",
+      "version": "0.3.1",
+      "source": "./",
+      "author": {
+        "name": "manalkaff",
+        "email": "manalkaff@gmail.com"
+      }
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "opendesign",
+  "description": "Open-source, skills-based version of Claude Design (claude.ai/design) for Claude Code. HTML pages, slide decks, interactive prototypes, UI kits, and brand systems — with taste, context-matching, and anti-slop discipline.",
+  "version": "0.3.1",
+  "author": {
+    "name": "manalkaff",
+    "email": "manalkaff@gmail.com"
+  },
+  "homepage": "https://github.com/manalkaff/opendesign",
+  "repository": "https://github.com/manalkaff/opendesign",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "claude-design",
+    "skills",
+    "design",
+    "ui",
+    "ux",
+    "prototyping",
+    "design-system",
+    "slides",
+    "wireframes",
+    "open-source"
+  ]
+}

.codex-plugin/plugin.json

@@ -0,0 +1,42 @@
+{
+  "name": "opendesign",
+  "version": "0.3.1",
+  "description": "Open-source, skills-based version of Claude Design (claude.ai/design). HTML pages, slide decks, interactive prototypes, UI kits, and brand systems.",
+  "author": {
+    "name": "manalkaff",
+    "email": "manalkaff@gmail.com",
+    "url": "https://github.com/manalkaff"
+  },
+  "homepage": "https://github.com/manalkaff/opendesign",
+  "repository": "https://github.com/manalkaff/opendesign",
+  "license": "MIT",
+  "keywords": [
+    "claude-design",
+    "design",
+    "ui",
+    "ux",
+    "prototyping",
+    "design-system",
+    "slides",
+    "wireframes"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "OpenDesign",
+    "shortDescription": "A senior designer for your coding agent — decks, prototypes, UI kits, brand systems.",
+    "longDescription": "OpenDesign is an open-source, skills-based version of Claude Design (claude.ai/design). It turns your coding agent into a senior designer: intake questions, context-matching, taste discipline, and a verifier pass on the output. Ships eight skills covering wireframes, interactive prototypes, slide decks, design systems, and developer handoff.",
+    "developerName": "manalkaff",
+    "category": "Design",
+    "capabilities": [
+      "Interactive",
+      "Read",
+      "Write"
+    ],
+    "defaultPrompt": [
+      "Make a pitch deck for a seed-stage company, 10 slides.",
+      "Design a settings page for this app using our existing design system.",
+      "I want to explore a few options for the onboarding flow. Rough sketches, nothing polished yet."
+    ],
+    "screenshots": []
+  }
+}

.cursor-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "opendesign",
+  "displayName": "OpenDesign",
+  "description": "Open-source, skills-based version of Claude Design (claude.ai/design). HTML pages, slide decks, interactive prototypes, UI kits, and brand systems.",
+  "version": "0.3.1",
+  "author": {
+    "name": "manalkaff",
+    "email": "manalkaff@gmail.com"
+  },
+  "homepage": "https://github.com/manalkaff/opendesign",
+  "repository": "https://github.com/manalkaff/opendesign",
+  "license": "MIT",
+  "keywords": [
+    "claude-design",
+    "design",
+    "ui",
+    "ux",
+    "prototyping",
+    "design-system",
+    "slides",
+    "wireframes"
+  ],
+  "skills": "./skills/"
+}

.gitattributes

@@ -33,3 +33,8 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+opendesign-example.png filter=lfs diff=lfs merge=lfs -text
+screenshot.png filter=lfs diff=lfs merge=lfs -text
+showcase1.gif filter=lfs diff=lfs merge=lfs -text
+showcase2.gif filter=lfs diff=lfs merge=lfs -text
+showcase3.gif filter=lfs diff=lfs merge=lfs -text

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,30 @@
+name: Bug report
+description: Report a skill behaving incorrectly.
+labels: ["bug"]
+body:
+  - type: input
+    id: skill
+    attributes:
+      label: Which skill?
+      placeholder: opendesign / wireframe / make-a-deck / ...
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: How to reproduce
+      description: Include the prompt you gave and the artifact the agent produced.
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Question or discussion
+    url: https://github.com/manalkaff/opendesign/discussions
+    about: For general questions and discussion, use Discussions instead of filing an issue.

.github/ISSUE_TEMPLATE/skill-request.yml

@@ -0,0 +1,34 @@
+name: Skill request
+description: Propose a new skill or a change to an existing one.
+labels: ["skill-request"]
+body:
+  - type: input
+    id: skill-name
+    attributes:
+      label: Skill name
+      description: Lowercase, hyphenated (e.g. animate-transitions).
+      placeholder: your-skill-name
+    validations:
+      required: true
+  - type: textarea
+    id: trigger
+    attributes:
+      label: When should the agent load this skill?
+      description: Write a "Use when..." sentence describing the triggering conditions. Not a summary of what the skill does.
+      placeholder: Use when the user asks for ...
+    validations:
+      required: true
+  - type: textarea
+    id: why-not-existing
+    attributes:
+      label: Why doesn't an existing skill cover this?
+      description: Check the existing skills in the README. Explain why none of them fit.
+    validations:
+      required: true
+  - type: textarea
+    id: rules
+    attributes:
+      label: Concrete rules the skill would enforce
+      description: What forbidden patterns, required constants, or specific behaviors would the body contain?
+    validations:
+      required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,32 @@
+<!--
+Thanks for the PR. Please fill in the relevant sections and delete the rest.
+-->
+
+## What this changes
+
+Briefly describe the change.
+
+## Type
+
+- [ ] New skill
+- [ ] Edit to an existing skill
+- [ ] Documentation
+- [ ] Tooling / infrastructure
+
+## If adding a new skill
+
+- [ ] `skills/<name>/SKILL.md` created with `name` + `description` frontmatter
+- [ ] Row added to the "Available skills" table in `README.md`
+- [ ] Versions bumped across all host configs (`plugin.json`, `marketplace.json`, `.cursor-plugin/`, `.codex-plugin/`, `gemini-extension.json`, `package.json`)
+
+Why can't an existing skill cover this case?
+
+## If editing an existing skill
+
+- [ ] `name` in frontmatter unchanged (or the change is called out as breaking)
+- [ ] `description` updated if the trigger shifted
+- [ ] Versions bumped if behavior changed
+
+## Notes
+
+Anything else a reviewer should know.

.github/workflows/validate.yml

@@ -0,0 +1,14 @@
+name: Validate skills
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run validator
+        run: ./validate-skills.sh

.gitignore

@@ -0,0 +1,10 @@
+node_modules/
+.DS_Store
+.env
+.env.*
+.claude/
+.worktrees/
+*.log
+.idea/
+.vscode/
+docs/superpowers

.opencode/INSTALL.md

@@ -0,0 +1,130 @@
+# Installing OpenDesign for OpenCode
+
+## Prerequisites
+
+- [OpenCode.ai](https://opencode.ai) installed
+
+## Installation
+
+### Project-level (recommended)
+
+Add opendesign to `.opencode/opencode.json` in your project root (create the file if it does not exist):
+
+```json
+{
+  "$schema": "../opencode-schema.json",
+  "plugin": [
+    "opendesign@git+https://github.com/manalkaff/opendesign.git"
+  ]
+}
+```
+
+> **Note:** Current OpenCode reads project-level config from `.opencode/opencode.json`, not from `opencode.json` or `.opencode.json` at the repo root. If you added the plugin to one of those locations and it is not loading, move it here.
+
+Restart OpenCode. The first install fetches the package from GitHub and may take 10–30 seconds while dependencies are reified — wait for it before assuming something failed.
+
+### Global (all projects)
+
+Add opendesign to your global config at `~/.config/opencode/opencode.json` or `~/.opencode/opencode.json`:
+
+```json
+{
+  "plugin": [
+    "opendesign@git+https://github.com/manalkaff/opendesign.git"
+  ]
+}
+```
+
+Restart OpenCode.
+
+## Verifying install
+
+After restarting, verify by asking: "What design skills do you have?"
+
+You should see opendesign skills listed. If skill count did not increase, check the logs (see Troubleshooting below).
+
+## Usage
+
+Use OpenCode's native `skill` tool:
+
+```
+use skill tool to list skills
+use skill tool to load opendesign
+```
+
+## Updating
+
+OpenDesign updates automatically when you restart OpenCode.
+
+If OpenCode still shows older skill content after restart, see `Troubleshooting -> Stale cached plugin content` below. In some cases OpenCode continues using an older cached package until that cache entry is removed.
+
+To pin a specific version:
+
+```json
+{
+  "plugin": ["opendesign@git+https://github.com/manalkaff/opendesign.git#v0.1.0"]
+}
+```
+
+## Troubleshooting
+
+### Plugin not loading
+
+1. Check logs for these key lines:
+
+   ```
+   project config loaded from .opencode/opencode.json   ← confirms correct config path
+   project .opencode reify                              ← npm install in progress
+   loading plugin                                       ← plugin being initialized
+   ```
+
+   Run: `opencode run --print-logs "hello" 2>&1 | grep -iE "opendesign|reify|project config|plugin"`
+
+2. Make sure the plugin entry is in `.opencode/opencode.json` (not `opencode.json` or `.opencode.json` at the repo root — those may be ignored by current OpenCode builds for project-level plugin loading).
+
+3. Make sure you are running a recent version of OpenCode.
+
+4. If you just added the plugin for the first time, wait 30 seconds on the next restart — the git package download and npm reify take time.
+
+### Skills not found
+
+1. Use `skill` tool to list what is discovered.
+2. Confirm the plugin loaded (see log check above).
+3. Confirm skill count increased after restart.
+
+### Stale cached plugin content
+
+If OpenCode loads the plugin but the skill text still looks outdated after you updated or reinstalled `opendesign`, OpenCode may be using a stale cached package copy under `~/.cache/opencode/packages/`.
+
+Symptoms include:
+
+- the plugin appears installed, but skill content still reflects an older revision
+- reinstalling in `~/.config/opencode/` or `~/.opencode/` does not change the loaded skill text
+- the cached package under `~/.cache/opencode/packages/` contains an older `opendesign` version than the one you expect
+
+Check the cached copy directly:
+
+```bash
+grep -n "design-systems" ~/.cache/opencode/packages/opendesign@git+https:/github.com/manalkaff/opendesign.git/node_modules/opendesign/skills/opendesign/SKILL.md
+```
+
+If that cached package is stale, remove it and restart OpenCode so it can fetch the current plugin again:
+
+```bash
+rm -rf ~/.cache/opencode/packages/opendesign@git+https:/github.com/manalkaff/opendesign.git
+```
+
+Then fully restart OpenCode and start a fresh session.
+
+### Tool mapping
+
+When skills reference Claude Code tools:
+- `TodoWrite` → `todowrite`
+- `Task` with subagents → `@mention` syntax
+- `Skill` tool → OpenCode's native `skill` tool
+- File operations → your native tools
+
+## Getting help
+
+- Report issues: https://github.com/manalkaff/opendesign/issues
+- Repo: https://github.com/manalkaff/opendesign

.opencode/plugins/opendesign.js

@@ -0,0 +1,100 @@
+/**
+ * OpenDesign plugin for OpenCode.ai
+ *
+ * Injects the opendesign bootstrap skill via chat transform,
+ * and registers the skills directory via config hook (no symlinks needed).
+ */
+
+import path from 'path';
+import fs from 'fs';
+import os from 'os';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Minimal frontmatter extractor (avoids external deps).
+const extractAndStripFrontmatter = (content) => {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) return { frontmatter: {}, content };
+
+  const frontmatterStr = match[1];
+  const body = match[2];
+  const frontmatter = {};
+
+  for (const line of frontmatterStr.split('\n')) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx > 0) {
+      const key = line.slice(0, colonIdx).trim();
+      const value = line.slice(colonIdx + 1).trim().replace(/^["']|["']$/g, '');
+      frontmatter[key] = value;
+    }
+  }
+
+  return { frontmatter, content: body };
+};
+
+const normalizePath = (p, homeDir) => {
+  if (!p || typeof p !== 'string') return null;
+  let normalized = p.trim();
+  if (!normalized) return null;
+  if (normalized.startsWith('~/')) {
+    normalized = path.join(homeDir, normalized.slice(2));
+  } else if (normalized === '~') {
+    normalized = homeDir;
+  }
+  return path.resolve(normalized);
+};
+
+export const OpenDesignPlugin = async ({ client, directory }) => {
+  const homeDir = os.homedir();
+  const opendesignSkillsDir = path.resolve(__dirname, '../../skills');
+  const envConfigDir = normalizePath(process.env.OPENCODE_CONFIG_DIR, homeDir);
+  const configDir = envConfigDir || path.join(homeDir, '.config/opencode');
+
+  const getBootstrapContent = () => {
+    const skillPath = path.join(opendesignSkillsDir, 'opendesign', 'SKILL.md');
+    if (!fs.existsSync(skillPath)) return null;
+
+    const fullContent = fs.readFileSync(skillPath, 'utf8');
+    const { content } = extractAndStripFrontmatter(fullContent);
+
+    const toolMapping = `**Tool Mapping for OpenCode:**
+When OpenDesign skills reference tools you don't have, substitute OpenCode equivalents:
+- \`TodoWrite\` → \`todowrite\`
+- \`Task\` tool with subagents → OpenCode's subagent system (@mention)
+- \`Skill\` tool → OpenCode's native \`skill\` tool
+- \`Read\`, \`Write\`, \`Edit\`, \`Bash\` → your native tools
+
+Use OpenCode's native \`skill\` tool to list and load the other OpenDesign skills (wireframe, make-a-deck, interactive-prototype, etc.) on demand.`;
+
+    return `<EXTREMELY_IMPORTANT>
+You have OpenDesign loaded.
+
+**The opendesign entry-point skill is included below. It is ALREADY LOADED — you are currently following it. Do NOT use the skill tool to load "opendesign" again.**
+
+${content}
+
+${toolMapping}
+</EXTREMELY_IMPORTANT>`;
+  };
+
+  return {
+    // Register the skills directory so OpenCode discovers every SKILL.md
+    // without the user editing opencode.json or symlinking.
+    config: async (config) => {
+      config.skills = config.skills || {};
+      config.skills.paths = config.skills.paths || [];
+      if (!config.skills.paths.includes(opendesignSkillsDir)) {
+        config.skills.paths.push(opendesignSkillsDir);
+      }
+    },
+
+    // Use system prompt transform for compatibility with current OpenCode builds.
+    'experimental.chat.system.transform': async (_input, output) => {
+      const bootstrap = getBootstrapContent();
+      if (bootstrap) {
+        (output.system ||= []).push(bootstrap);
+      }
+    }
+  };
+};

AGENTS.md

@@ -0,0 +1,37 @@
+# Agent instructions for this repository
+
+This repo is **OpenDesign** — an open-source, skills-based version of [Claude Design](https://claude.ai/design) (the web design mode on claude.ai), packaged as a Claude Code plugin. When working inside this repository, your job is to maintain and extend those skills — not to run them.
+
+## Repo layout
+
+- `skills/<skill-name>/SKILL.md` — one folder per skill. Each `SKILL.md` has YAML frontmatter (`name`, `description`) followed by the skill body.
+- `.claude-plugin/plugin.json` — Claude Code plugin metadata.
+- `.claude-plugin/marketplace.json` — Claude Code marketplace entry. Skills are discovered by convention from `./skills/`; do not add a `skills[]` field (Claude Code's schema rejects it).
+- `.cursor-plugin/plugin.json` — Cursor plugin metadata.
+- `.codex-plugin/plugin.json` — Codex plugin metadata (richer `interface` block for app UI).
+- `.opencode/plugins/opendesign.js` — OpenCode plugin (registers skills dir + injects `opendesign` bootstrap into the first user message).
+- `.opencode/INSTALL.md` — user-facing install notes for OpenCode.
+- `gemini-extension.json` + `GEMINI.md` — Gemini CLI extension. `GEMINI.md` `@-`imports the `opendesign` skill as context.
+- `package.json` — required so OpenCode can install the repo via `git+https://...`. `main` points at the OpenCode plugin entry.
+- `README.md` — user-facing. The "Available skills" table must match the actual skills shipped.
+
+## Rules when editing skills
+
+- Skills are written in direct imperative voice. No marketing language, no apologies, no emoji.
+- Every `SKILL.md` must start with frontmatter containing `name` and `description`. `description` is a "Use when..." sentence that describes triggering conditions, not a summary of what the skill does.
+- Keep `opendesign/SKILL.md` as the entry-point/base skill. Specialist skills (`wireframe`, `make-a-deck`, etc.) are loaded on demand by the workflow described there.
+- If you add a new skill: create `skills/<name>/SKILL.md` with frontmatter and add a row to the README table. Do not add a per-skill list to `.claude-plugin/marketplace.json`; Claude Code discovers skills from `./skills/`.
+- If you rename or remove a skill: update the README table and any direct references to that skill in the same change.
+
+## Rules when editing the plugin config
+
+- `name` must match across every host config: `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` (both top-level and `plugins[0].name`), `.cursor-plugin/plugin.json`, `.codex-plugin/plugin.json`, `gemini-extension.json`, and `package.json`.
+- Bump `version` everywhere together: both `.claude-plugin/*.json` files, `.cursor-plugin/plugin.json`, `.codex-plugin/plugin.json`, `gemini-extension.json`, and `package.json`. Also add a new section to `VERSIONS.md`.
+- `.opencode/plugins/opendesign.js` bootstraps from `skills/opendesign/SKILL.md`. If you rename or remove that skill, update the path in the JS.
+- Do not add secrets or personal paths to any config file.
+
+## Style
+
+- Concrete beats vague ("Use `#246BFD` for primary buttons" beats "use a blue tone").
+- Specific rules and forbidden patterns beat aspirational prose.
+- Prefer editing existing skills over adding new ones.

CLAUDE.md

@@ -0,0 +1,37 @@
+# Agent instructions for this repository
+
+This repo is **OpenDesign** — an open-source, skills-based version of [Claude Design](https://claude.ai/design) (the web design mode on claude.ai), packaged as a Claude Code plugin. When working inside this repository, your job is to maintain and extend those skills — not to run them.
+
+## Repo layout
+
+- `skills/<skill-name>/SKILL.md` — one folder per skill. Each `SKILL.md` has YAML frontmatter (`name`, `description`) followed by the skill body.
+- `.claude-plugin/plugin.json` — Claude Code plugin metadata.
+- `.claude-plugin/marketplace.json` — Claude Code marketplace entry. Skills are discovered by convention from `./skills/`; do not add a `skills[]` field (Claude Code's schema rejects it).
+- `.cursor-plugin/plugin.json` — Cursor plugin metadata.
+- `.codex-plugin/plugin.json` — Codex plugin metadata (richer `interface` block for app UI).
+- `.opencode/plugins/opendesign.js` — OpenCode plugin (registers skills dir + injects `opendesign` bootstrap into the first user message).
+- `.opencode/INSTALL.md` — user-facing install notes for OpenCode.
+- `gemini-extension.json` + `GEMINI.md` — Gemini CLI extension. `GEMINI.md` `@-`imports the `opendesign` skill as context.
+- `package.json` — required so OpenCode can install the repo via `git+https://...`. `main` points at the OpenCode plugin entry.
+- `README.md` — user-facing. The "Available skills" table must match the actual skills shipped.
+
+## Rules when editing skills
+
+- Skills are written in direct imperative voice. No marketing language, no apologies, no emoji.
+- Every `SKILL.md` must start with frontmatter containing `name` and `description`. `description` is a "Use when..." sentence that describes triggering conditions, not a summary of what the skill does.
+- Keep `opendesign/SKILL.md` as the entry-point/base skill. Specialist skills (`wireframe`, `make-a-deck`, etc.) are loaded on demand by the workflow described there.
+- If you add a new skill: create `skills/<name>/SKILL.md` with frontmatter and add a row to the README table. Do not add a per-skill list to `.claude-plugin/marketplace.json`; Claude Code discovers skills from `./skills/`.
+- If you rename or remove a skill: update the README table and any direct references to that skill in the same change.
+
+## Rules when editing the plugin config
+
+- `name` must match across every host config: `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json` (both top-level and `plugins[0].name`), `.cursor-plugin/plugin.json`, `.codex-plugin/plugin.json`, `gemini-extension.json`, and `package.json`.
+- Bump `version` everywhere together: both `.claude-plugin/*.json` files, `.cursor-plugin/plugin.json`, `.codex-plugin/plugin.json`, `gemini-extension.json`, and `package.json`. Also add a new section to `VERSIONS.md`.
+- `.opencode/plugins/opendesign.js` bootstraps from `skills/opendesign/SKILL.md`. If you rename or remove that skill, update the path in the JS.
+- Do not add secrets or personal paths to any config file.
+
+## Style
+
+- Concrete beats vague ("Use `#246BFD` for primary buttons" beats "use a blue tone").
+- Specific rules and forbidden patterns beat aspirational prose.
+- Prefer editing existing skills over adding new ones.

CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing to OpenDesign
+
+Thanks for considering a contribution. OpenDesign is an open-source, skills-based version of [Claude Design](https://claude.ai/design) — the goal is parity with that experience, not feature creep. This repo ships a small, opinionated set of skills; quality bar is higher than coverage. Before adding a new skill, strongly consider whether an existing one can be extended instead.
+
+## Ground rules
+
+- Every `SKILL.md` is written in direct imperative voice. No marketing language, no apologies, no emoji, no "as we discussed".
+- Concrete beats vague. Specific rules, forbidden patterns, and measured constants beat aspirational prose.
+- Skills describe *behavior under specific conditions*, not philosophies. If your skill body is abstract, it's not ready.
+
+## SKILL.md format
+
+```markdown
+---
+name: your-skill-name
+description: Use when [specific triggering conditions]. [One-line summary of what it produces.]
+---
+
+Loaded when [restate trigger].
+
+## [Section]
+
+[Rules, constants, forbidden patterns, required paths. Be concrete.]
+```
+
+Rules:
+
+- `name` uses lowercase and hyphens. Must match the folder name.
+- `description` starts with "Use when..." and describes *when the skill applies*, not what it does internally. The agent reads this to decide whether to load the skill.
+- Do not summarize the skill's workflow in the description — the skill body is authoritative.
+
+## Adding a new skill
+
+1. Create `skills/<name>/SKILL.md` with frontmatter and body.
+2. Add a row to the "Available skills" table in `README.md`.
+3. Open a PR. In the description, state:
+   - What the skill does.
+   - Why existing skills can't cover this case.
+   - Any risk of overlap with `opendesign`, `frontend-design`, `create-design-system`, or `make-a-deck`.
+
+## Editing an existing skill
+
+- Keep the frontmatter `name` stable — changing it is a breaking change for users.
+- If you're narrowing or widening the trigger, update the `description` in the same change.
+- Bump the version in every host config for any user-visible change. Run `bash validate-skills.sh` to catch version drift.
+
+## Things I'll reject
+
+- Skills that replicate what an existing skill covers with minor variation.
+- Skill bodies that read like a blog post or pitch.
+- Emoji, marketing adjectives, or aspirational prose.
+- Frontmatter that summarizes the skill's workflow instead of its trigger.
+- PRs that add a skill file but forget the README update.

GEMINI.md

@@ -0,0 +1 @@
+@./skills/opendesign/SKILL.md

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 manalkaff
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,11 +1,165 @@
 ---
 license: mit
-tags:
-- opendesign
 language:
 - es
+tags:
+- opendesign
+- design
+- skills
+- agents
 ---
 
 # OpenDesign
 
-Modelo placeholder. Sube aquí los pesos (`config.json`, `*.safetensors`, tokenizer, etc.) cuando estén disponibles.
+## Why this exists
+
+Claude Design on claude.ai is excellent. But it's locked.
+
+Locked to the browser. Locked to Anthropic models. Locked to the web app — which means no access to your local files, no integration with your existing design system, and no way to use it inside the editor where your actual work happens.
+
+I built OpenDesign to fix that. Same philosophy as Claude Design — structured intake, context-matching, taste, a verifier that checks the output against the brief — but packaged as portable markdown skills you can install in Claude Code, Cursor, Codex, Gemini CLI, or OpenCode. It runs locally, reads your codebase, and works with whatever model you're on.
+
+You own it. You can read every skill, fork it, and extend it.
+
+## What it does
+
+OpenDesign turns your AI coding agent into a designer with taste, opinions, and the discipline to restrain them. HTML is the output medium. Inside that medium it embodies whichever specialist the task calls for — deck designer, UX designer, prototyper, brand designer.
+
+It doesn't generate generic AI output. It reads your actual codebase first.
+
+![OpenDesign extracting the ReelPilot design system live from the codebase](screenshot.png)
+*OpenDesign extracting a live design system from a real codebase — colors, typography, tokens, all sourced directly from `src/app.css`.*
+
+## Showcase
+
+![OpenDesign demo](showcase1.gif)
+
+![OpenDesign demo 2](showcase2.gif)
+
+![OpenDesign demo 3](showcase3.gif)
+
+Ten skills ship together. One is the entry point (`opendesign`); the others are loaded on demand by the workflow.
+
+## Available skills
+
+<!-- SKILLS:START -->
+
+| Skill | Use when |
+|---|---|
+| `opendesign` | Starting any design task. Establishes the base role, workflow, and taste rules, and routes to specialist skills. |
+| `setup-opendesign` | Initialising OpenDesign for the first time in a project. Creates output folders, copies the viewer, and writes an empty manifest. Called automatically by `opendesign` — rarely needed directly. |
+| `run-opendesign` | Starting the preview server after a build. Serves `./opendesign/` on port 8289, handles duplicate prevention and python/node detection, and prints a clickable link. Called automatically by `opendesign` — rarely needed directly. |
+| `create-design-system` | Producing a reusable design system or UI kit from an existing brand, codebase, or product. |
+| `frontend-design` | Designing without an existing brand system. Pushes for a committed, distinctive aesthetic. |
+| `wireframe` | Exploring the design space quickly — many rough ideas, not one polished direction. |
+| `interactive-prototype` | Asking for a working, clickable prototype that behaves like a real app. |
+| `make-a-deck` | Asking for a slide presentation. Fixed 1920×1080 canvas, chapter-driven titles. |
+| `make-tweakable` | Wanting in-design controls for toggling variants, colors, copy, or feature flags. |
+| `handoff-to-claude-code` | Handing a finished design off to a developer or coding agent for implementation. |
+
+<!-- SKILLS:END -->
+
+## How the skills work together
+
+`opendesign` is the front door. On invocation it:
+
+1. Scans `./opendesign/design-systems/*/` for existing systems (looking for `SKILL.md` or `tokens/colors_and_type.css` as markers).
+2. Announces what it found and picks the right one, asks, or offers to create one.
+3. Runs a structured intake if the work is new.
+4. Routes to the specialist skill for the artifact (deck → `make-a-deck`, prototype → `interactive-prototype`, etc.).
+5. Forks a verifier subagent to review against the brief.
+
+Design systems created by `create-design-system` are written to `./opendesign/design-systems/<name>/` so `opendesign` can auto-discover them in future sessions. Multiple systems per project are supported — a marketing system, a product system, a deck template — and the agent picks based on task shape.
+
+## Installation
+
+**Note:** Installation differs by platform.
+
+### Claude Code
+
+```bash
+/plugin marketplace add manalkaff/opendesign
+/plugin install opendesign@opendesign
+```
+
+### Cursor
+
+In Cursor Agent chat:
+
+```text
+/add-plugin opendesign
+```
+
+Or search for "opendesign" in the plugin marketplace.
+
+### OpenAI Codex CLI
+
+Open the plugin search:
+
+```bash
+/plugins
+```
+
+Search for `opendesign` and select **Install Plugin**.
+
+### OpenAI Codex App
+
+In the Codex app, click **Plugins** in the sidebar, find **OpenDesign** in the Design section, click the `+`, and follow the prompts.
+
+### Gemini CLI
+
+```bash
+gemini extensions install https://github.com/manalkaff/opendesign
+```
+
+To update:
+
+```bash
+gemini extensions update opendesign
+```
+
+### OpenCode
+
+Tell OpenCode:
+
+```
+Fetch and follow instructions from https://raw.githubusercontent.com/manalkaff/opendesign/main/.opencode/INSTALL.md
+```
+
+### Fork
+
+Fork the repo, add your own skills under `skills/`, and install your fork through whichever host you use.
+
+## Usage
+
+Once installed, invoke with `/opendesign` and describe what you want. The agent picks up the right skills on its own.
+
+```
+/opendesign make a pitch deck for a seed-stage AI company, 10 slides
+```
+
+```
+/opendesign design a settings page for this React app — use our existing design system
+```
+
+```
+/opendesign explore a few options for the onboarding flow. rough sketches, nothing polished yet
+```
+
+```
+/opendesign extract our design system from the codebase and document it
+```
+
+## Upgrading
+
+If you installed via the plugin marketplace, run `/plugin update opendesign` inside Claude Code.
+
+If you cloned or submoduled, `git pull` in the repo.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Quality bar is higher than coverage — consider extending an existing skill before adding a new one.
+
+## License
+
+[MIT](LICENSE)

VERSIONS.md

@@ -0,0 +1,37 @@
+# Versions
+
+## 0.3.1
+
+Bug fixes for `run-opendesign` and `setup-opendesign`.
+
+- `setup-opendesign` — fixed viewer.html fetch URL (`open-design` → `opendesign`), preventing a potential silent hijack if the old repo name is reclaimed.
+- `run-opendesign` — port check now probes `/opendesign/index.html` for a 200 before treating :8289 as the OpenDesign server; a foreign process on that port now surfaces a clear error instead of a dead link.
+- `run-opendesign` — added platform detection (`uname -s`); Windows path uses `netstat` for port checks, `python`-first runtime priority, and `Start-Process` for background launch.
+
+## 0.3.0
+
+Preview server — clickable link after every build, no manual terminal commands.
+
+- `run-opendesign` — new skill. Checks if port 8289 is already in use, detects python3/python/node, starts the server in the background, prints `http://localhost:8289/opendesign/` as a clickable link.
+- `opendesign` — step 5 now dispatches `run-opendesign` after writing the manifest instead of telling the user to open the file manually.
+
+## 0.2.0
+
+Mockup viewer — browse and preview all mockups from a single page.
+
+- `setup-opendesign` — new first-run setup skill. Downloads `viewer.html` from GitHub, creates output folders, initialises `manifest.json`. Called automatically by `opendesign`.
+- `opendesign` — step 1 now dispatches `setup-opendesign` on first run; step 5 now scans and rewrites `manifest.json` after every build.
+- `viewer.html` — pre-built HTML viewer shipped with the plugin. Dark sidebar, iframe preview, collapsible groups, empty state. No dependencies.
+
+## 0.1.0
+
+Initial release. Open-source, skills-based implementation of [Claude Design](https://claude.ai/design) for Claude Code.
+
+- `opendesign` — entry-point skill. Workflow, questioning protocol, taste rules, design-system discovery.
+- `create-design-system` — builds reusable systems at `./design-systems/<name>/` with discovery markers.
+- `frontend-design` — committed, distinctive aesthetic when no brand exists.
+- `wireframe` — low-fi breadth-first exploration, 3–5 structurally distinct options.
+- `interactive-prototype` — clickable React prototypes with working state.
+- `make-a-deck` — slide-native presentations on a fixed 1920×1080 canvas.
+- `make-tweakable` — in-design Tweaks panel with host handshake.
+- `handoff-to-claude-code` — developer handoff folder, spec README, zipped.

gemini-extension.json

@@ -0,0 +1,6 @@
+{
+  "name": "opendesign",
+  "description": "Open-source, skills-based version of Claude Design (claude.ai/design). HTML pages, slide decks, interactive prototypes, UI kits, and brand systems.",
+  "version": "0.3.1",
+  "contextFileName": "GEMINI.md"
+}

package.json

@@ -0,0 +1,6 @@
+{
+  "name": "opendesign",
+  "version": "0.3.1",
+  "type": "module",
+  "main": ".opencode/plugins/opendesign.js"
+}

skills/create-design-system/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: create-design-system
+description: Use when the user asks to produce a reusable design system or UI kit from an existing brand, codebase, or product. Writes to ./opendesign/design-systems/<name>/ so opendesign can auto-discover it in future sessions.
+---
+
+Loaded when the user asks you to produce a reusable design system or UI kit from an existing brand, codebase, or product.
+
+## Where design systems live
+
+All design systems for a project live under `./opendesign/design-systems/<name>/`. Multiple systems can coexist — for example, `./opendesign/design-systems/marketing/`, `./opendesign/design-systems/product/`, `./opendesign/design-systems/deck-template/`. The name is required and descriptive of what the system is for (brand surface, product surface, deck template, co-brand partner). Never use `design-system/` singular or generic names like `main`.
+
+A folder is recognized as a design system if it contains **either** a `SKILL.md` **or** a tokens file (`colors_and_type.css` at the root, or `tokens/colors_and_type.css` nested). `opendesign` accepts either marker when detecting systems. Always write both: the `SKILL.md` makes the folder portable as a standalone agent skill, and the tokens file is the canonical output of this skill.
+
+## Required paths (non-negotiable)
+
+Every generated system MUST write to these exact paths, relative to project root. `opendesign` auto-discovery depends on them — deviating breaks detection.
+
+- `./opendesign/design-systems/<name>/SKILL.md` — portable skill marker.
+- `./opendesign/design-systems/<name>/tokens/colors_and_type.css` — canonical tokens file. Nested under `tokens/`, not at the folder root. This is the discovery marker.
+- `./opendesign/design-systems/<name>/README.md` — human-facing index.
+
+Do not write the tokens file to any other path (no `colors.css`, no `styles/tokens.css`, no flat `colors_and_type.css` at the root of the system folder). Do not omit `SKILL.md`. Do not rename the `design-systems/` parent inside `opendesign/`.
+
+## What a design system folder contains
+
+```
+opendesign/design-systems/<name>/
+  README.md
+  tokens/
+    colors_and_type.css
+  fonts/
+    [font files the brand actually ships]
+  assets/
+    logos/
+    icons/
+    imagery/
+  brand/
+    voice-and-tone.md
+    style-notes.md
+  ui-kit-<product>/
+    components/        # JSX components, one per file
+    index.html         # interactive showcase of core screens
+  sample-slides/       # only if a deck template was provided
+```
+
+## Process
+
+1. **Explore provided assets.** Read the codebase, the Figma file (via its design context API when available), screenshots, decks. Prefer codebase source and Figma data over screenshots in every case.
+2. **Write the README.** State your understanding of the brand, list every source you consulted, and provide an index into the rest of the folder.
+3. **Extract tokens.** Write color and type tokens to exactly `./opendesign/design-systems/<name>/tokens/colors_and_type.css` — not the folder root, not a renamed file. Also write `./opendesign/design-systems/<name>/SKILL.md` so the folder is recognized and portable. Define raw variables (`--fg-1`, `--fg-2`, `--bg-1`, `--accent-1`, font families, weights, size steps) and semantic variables (`--h1`, `--h2`, `--body`, `--caption`, `--surface-primary`, `--border-subtle`, etc.). Semantic vars reference raw vars.
+4. **Document content fundamentals.** Voice, tone, casing (title case vs sentence case), punctuation rules, emoji use, numeric formatting, how the brand talks to users versus about itself.
+5. **Document visual foundations.** Color (roles, not just swatches), type (scale, pairing, usage rules), spacing (scale + when to apply), backgrounds (treatments and when each appears), motion (timings, easing, common patterns), hover and press states, borders, shadows, radii, card patterns, imagery vibe.
+6. **Document iconography.** Icon fonts, SVG sprites, raster assets, emoji policy, unicode usage. Copy the real asset files into `assets/`. Never hand-draw.
+7. **Build UI kits per product.** Pixel-perfect recreations of existing components as JSX, one component per file, token-driven. Provide `index.html` that assembles the core screens so the kit can be reviewed interactively.
+8. **Build sample slides.** Only if a deck template was given. Use the deck skill's conventions.
+
+## Hard rules
+
+- Never recreate UIs from screenshots alone when the codebase is available. Codebase is source of truth; screenshots are lossy.
+- Never read SVG source files. They burn context for no benefit. Copy the file into `assets/` and reference it by filename.
+- Never hand-draw SVGs. Copy the real assets.
+- Never invent components. UI kits recreate what exists. If a component is not in the source, leave it out or stub it with a labeled placeholder. Do not fill gaps with your own interpretation.
+- Stop and ask if key resources (codebase, Figma file, brand guidelines) are inaccessible. Do not proceed on guesswork.
+- Avoid visual motif defaults the industry has exhausted: bluish-purple gradients, emoji-as-feature-cards, rounded cards with a colored left-border accent strip.
+
+## Ending the task
+
+Close with a clear ask to iterate: list the parts you were confident about, the parts you were unsure about, and the decisions you want the user to confirm before the system is considered canonical.

skills/frontend-design/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: frontend-design
+description: Use when designing without an existing brand system. Pushes for a committed, distinctive aesthetic rather than generic defaults — extreme directions, bold typography, decisive color commitment.
+---
+
+Loaded when designing without an existing brand system. Push for a committed, distinctive aesthetic. Generic defaults are a failure state.
+
+## Output location
+
+Write all output files to `./opendesign/mockups/<task-slug>/`. Derive the slug from the page or feature name (e.g. `landing-page`, `pricing-redesign`).
+
+## Pre-build thinking
+
+Before touching HTML, answer three questions in your plan:
+- **Purpose.** What job does this page do in one sentence?
+- **Tone.** Which human adjective describes the feeling — clinical, warm, severe, playful, reverent, brash?
+- **Differentiation.** What would make a viewer remember this over a generic SaaS landing page?
+
+Pick an extreme direction and execute it with precision: brutalist, maximalist, editorial, retro-futuristic, organic, industrial, anti-design, swiss-modernist, zine-punk. Indecisive middles read as stock templates.
+
+## Typography
+
+Pair a distinctive display face with a refined body face. Avoid Inter, Roboto, Arial, and generic system stacks. Candidates: editorial serifs (Fraunces, GT Sectra, Tiempos), geometric display (Space Grotesk, PP Neue Montreal, Söhne Breit), mono accents (JetBrains Mono, IBM Plex Mono), quirky unicase and variable fonts where the direction supports it. Set a real type scale with intentional ratios; do not rely on default browser sizes.
+
+## Color
+
+Commit to a cohesive palette. Dominant colors with one or two sharp accents outperform timid even distribution. Use oklch for accents so chroma and lightness stay consistent across hues. Restrict neutrals to chroma ≤ 0.02.
+
+## Motion
+
+One or two high-impact motion moments beat a dozen scattered micro-interactions. Favor CSS-only animation: transforms, transitions, `@keyframes`, `scroll-timeline` where it is supported. Reserve JS for motion that depends on state.
+
+## Spatial composition
+
+Break the grid deliberately: asymmetry, overlap, diagonal baselines, oversized type against tight columns, generous negative space — or controlled, dense information surfaces if the aesthetic demands it. Either direction beats an evenly padded three-column grid.
+
+## Backgrounds
+
+Default to atmosphere: gradient meshes, film grain, noise, layered transparencies, dramatic shadows, tinted halftones, subtle paper textures. Flat white on flat black is a choice, not a default — use it only when the direction demands it.
+
+## Variation across generations
+
+Never converge on the same choices across different projects or variation runs. Rotate axes: aesthetic direction, dominant hue family, typographic register, motion philosophy, compositional strategy. Two designs in a row should not feel like siblings unless the user asked for continuity.
+
+## Matching complexity to direction
+
+Maximalist direction → elaborate implementation: layered textures, dense type, rich motion, intricate detail.
+Minimalist direction → restrained implementation: fewer elements, tighter type scale, longer transitions, more white.
+Do not half-commit. A restrained layout executed with maximalist intent reads as unfinished; a maximalist layout executed with minimalist intent reads as confused.

skills/handoff-to-claude-code/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: handoff-to-claude-code
+description: Use when the user asks to hand a finished design off to a developer or a coding agent for implementation in a real codebase. Produces a self-sufficient handoff folder with a spec README, zipped for download.
+---
+
+Loaded when the user asks to hand a finished design off to a developer or a coding agent for implementation in a real codebase. The output of this skill is a self-sufficient handoff folder, zipped and presented to the user for download.
+
+## Folder setup
+
+- Create a folder at `./opendesign/handoffs/<feature-slug>/`. Slug describes the feature (e.g. `onboarding-flow`, `settings-redesign`). Never `handoff/`, `export/`, or similar generics at the project root.
+- Copy every relevant HTML prototype, component file, image, font, and referenced asset into the folder. The developer must not have to trace paths back into the main project tree.
+- Generate `README.md` at the root of the folder. Everything the developer needs to act on lives in the README.
+
+## README structure
+
+Every section below is required. Use these exact headings in this order.
+
+1. **Overview.** One short paragraph: what the feature is and what it accomplishes. No design history.
+2. **About the design files.** Disclaimer up front, verbatim in spirit: the HTML files in this bundle are *design references*, not production code to copy directly. The developer's task is to recreate the designs in the target codebase's existing framework (React, Vue, SwiftUI, native, etc.) using its established patterns and libraries. If no codebase exists yet, pick the most appropriate framework for the project.
+3. **Fidelity.** State explicitly whether the designs are high-fidelity (pixel-perfect; recreate exactly) or low-fidelity (wireframe; use for layout and flow, apply the existing design system for styling). This call changes how much of the rest of the README is authoritative.
+4. **Screens / views.** For every screen in the design, document:
+   - Name and purpose.
+   - Layout — grid structure, flex direction, widths, heights, margins, padding. Exact values.
+   - Components. For each: position and size, exact colors (hex), typography (family, size, weight, line-height, letter-spacing), border radius, shadows, borders, hover / active / focus states, exact copy.
+5. **Interactions and behavior.** Click handlers, navigation flows, animations (duration, easing, animated properties), hover states, loading states, error states, form validation rules, responsive behavior where applicable.
+6. **State management.** State variables, transitions and their triggers, data-fetching requirements.
+7. **Design tokens.** Colors (with hex), spacing scale, type scale, border radii, shadows. Flat list, not prose.
+8. **Assets.** Every image, icon, font, or other asset used in the design, with its source.
+9. **Files.** List the HTML/CSS/JS files included in the bundle and what each one corresponds to.
+
+## Hard rules
+
+- Be extremely precise about measurements, colors, and typography. The developer is implementing from this document, not eyeballing the HTML.
+- State up front that the HTML is a reference, not the shipping artifact. This is the single most important thing for the developer to understand — without it they may paste the prototype into the codebase and ship it.
+- If the design uses brand assets, tell the developer to pull from the codebase's existing brand system, not to copy the embedded copies from the HTML.
+- Before finishing, ask the user whether they want screenshots of the designs included in the bundle. Do not include them by default.
+- After writing the folder, zip it and present the archive to the user for download. Name the zip `<feature-slug>.zip`.
+
+## README tone
+
+- Write for a developer who was not in the design conversation. No "as we discussed." No assumed context.
+- Imperative and concrete. "Use `#246BFD` for primary buttons" beats "the primary button should use a blue tone."
+- No rationale or design justification unless the developer needs it to implement correctly. This is a spec, not a pitch.

skills/interactive-prototype/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: interactive-prototype
+description: Use when the user asks for a working, clickable prototype — something that behaves like a real app rather than a static mockup. React + useState/useEffect, realistic fake data, working state transitions.
+---
+
+Loaded when the user asks for a working, clickable prototype — something that behaves like a real app rather than a static mockup.
+
+## Output location
+
+Write all output files to `./opendesign/mockups/<task-slug>/`. Derive the slug from the feature name (e.g. `checkout-flow`, `settings-panel`).
+
+## Role framing
+
+The output is a prototype that feels like a real product, not a storyboard. State transitions work. Forms validate. Buttons route to something. If an interaction is visible in the UI, it actually happens.
+
+It is still a prototype. Cut corners on backend, real persistence, and edge cases. Fake data is fine. Real logic for the happy path is required.
+
+## Stack and structure
+
+- React with `useState` and `useEffect` for local state and effects. Keep state colocated. No global store unless the prototype genuinely needs one.
+- Split the prototype into small, readable components. Files over ~400 lines get broken up.
+- Inline JSX via Babel is fine for a single-file prototype. For anything multi-screen, split into per-screen component files and compose them.
+- Wrap the prototype in an appropriate device or window frame — phone bezel, browser chrome, desktop window — so it reads as a product, not a web page.
+
+## Required interaction surface
+
+- Hover states on every interactive element.
+- Click and tap handlers that route to the next state. No dead controls.
+- Form validation on the happy path: buttons disabled until inputs are valid, visible error states when they are not.
+- Animated transitions between states and screens. Short, purposeful, not decorative.
+- Multi-step flows work end to end. The user can walk the intended happy path without hitting a dead end.
+- Loading and empty states where the real product would have them. Do not skip straight to populated views.
+
+## Realism rules
+
+- Realistic fake data. No lorem ipsum. No "John Doe." Names, copy, numbers, and timestamps fit the product's world.
+- Mobile frames: hit targets minimum 44px.
+- Persist critical state — current screen, active tab, demo playback position — in `localStorage` so a refresh during iteration does not lose the user's place.
+
+## What to leave out
+
+- Real authentication, real network calls, real persistence beyond `localStorage`.
+- Production-grade accessibility audits. Basic semantics and focus management are enough.
+- Every possible edge case. Pick the paths the user wants to demonstrate and make those watertight.

skills/make-a-deck/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: make-a-deck
+description: Use when the user asks for a slide presentation. Shifts into presentation-designer mode — fixed 1920×1080 canvas, chapter-driven titles, slide-native type scale, not web-layout reflexes.
+---
+
+Loaded when the user asks for a slide presentation.
+
+## Output location
+
+Write all output files to `./opendesign/mockups/<task-slug>/`. Derive the slug from the deck topic (e.g. `q3-board-update`, `product-launch`).
+
+## Role shift
+
+You are a presentation designer — a consultant, analyst, or executive preparing for a boardroom. You are not a web designer. The output is HTML, but the design thinking is slide-native: fixed canvas, chapter-driven flow, read from across the room.
+
+## Intake
+
+Ask for deck length in minutes if it is not given. Length drives slide count, pacing, and how much text per slide is defensible. Also confirm: audience, delivery mode (live vs. read-alone), brand context, required sections.
+
+## Canvas
+
+- 1920×1080 by default. Fixed-size canvas. Letterbox on smaller viewports; scale uniformly with JS.
+- One `<section>` per slide.
+- Never reflow slides to viewport width. Slides are compositions, not responsive pages.
+
+## Type scale and spacing constants
+
+Define these at the top of the stylesheet and reference them from every slide. Never use ad-hoc pixel values.
+
+```css
+:root {
+  --title: 64px;
+  --subtitle: 44px;
+  --body: 34px;
+  --small: 28px;
+
+  --pad-top: 100px;
+  --pad-bottom: 80px;
+  --pad-x: 100px;
+  --title-gap: 52px;
+  --item-gap: 28px;
+}
+```
+
+Adjust the numbers to the brand if one is given, but the structure stays the same: named constants only, referenced everywhere.
+
+Web defaults (14–16px body, 48–72px padding) are too small for slides. Do not regress to them.
+
+When the user specifies sizes in points, convert: `px = pt × 1.333`. "36pt body" → 48px body.
+
+## Title discipline
+
+- Pick ONE grammatical style for titles across the entire deck and stick to it. Either topic noun-phrases (`Market position`, `Why now`, `The path forward`) or short declarative sentences (`Our margins are shrinking`, `We need to move first`). Do not mix.
+- Titles should read like chapters. Someone reading only the titles should follow the story.
+- The title sequence is a standalone deliverable. Write every title first. Read them back as a block. Check they tell the story of the deck without any slide content. Revise until the title list alone is coherent.
+
+### AI-isms to refuse
+
+- Overdramatic verdicts: "The future is here." "The time is now." "Everything changes."
+- "It's not X. It's Y." framings and other speaker-punchline constructions.
+- Faux-insight ("Innovation reimagined.") and abstract-noun stacking ("Scale. Momentum. Trust.").
+- Rhetorical questions posing as headlines.
+
+## Content density
+
+Avoid walls of text. Prefer tables, diagrams, quotes, images, and single dominant figures. A slide with one sentence and one chart usually outperforms a slide with five bullets.
+
+## Visual variety
+
+Mix slide types across the deck: full-bleed image slides, large-figure slides, quote slides, table slides, textual slides, section headers. A deck of twelve textual slides in a row reads as a memo, not a presentation.
+
+## Parallelism
+
+- Section header slides must be visually identical to each other across the deck — same layout, same type treatment, same position of the section number.
+- Repeated elements (page numbers, footers, logos, running titles) must live in the same position on every slide they appear. Pixel-level consistency.
+
+## Image handling
+
+- **Full-bleed** for atmospheric imagery: edge-to-edge, no padding, optional overlay.
+- **Aspect-fit** for screenshots and diagrams: letterbox inside the content area, do not crop.
+- **Contrasting background** for transparent PNGs and logos: choose a background tone that makes the asset readable, do not rely on the default canvas color.
+
+## Forbidden deck tropes
+
+- Takeaway boxes in the lower-right corner.
+- Cards with a colored left-border accent strip.
+- Accent-border call-out boxes in general.
+- Emoji used as iconography.
+- Self-drawn SVG illustrations or diagrams. Use brand icons, user-provided images, or labeled placeholders.
+- Gradient backgrounds used as a default wash.
+
+## Planning steps (run in order)
+
+1. Ask the intake questions.
+2. Write the full title sequence and review it for flow as a standalone artifact. Revise before building anything.
+3. Define `TYPE_SCALE` and `SPACING` constants.
+4. Build slides. Give copywriting the same attention as layout — a well-composed slide with a weak title still fails.
+
+## Verification reminder
+
+Open space in the bottom third of a slide is correct slide composition, not a defect. Slides are read across a room; margins are functional. Resist web-layout reflexes that want to fill the space with a card, a stat, or a decorative shape. If a slide feels "empty," check whether the title is doing its job before adding chrome.

skills/make-tweakable/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: make-tweakable
+description: Use when the user wants in-design controls for toggling variants, swapping colors, editing copy, or flipping feature flags directly inside a design artifact. Adds a Tweaks panel and host handshake.
+---
+
+Loaded when the user wants in-design controls for toggling variants, swapping colors, editing copy, or flipping feature flags directly inside a design artifact.
+
+## What to expose
+
+A small number of high-impact values. Good candidates: one or two key colors, a layout variant toggle, a feature flag, a headline copy field. Do not over-expose. Every additional control raises the cost of the design and dilutes the point.
+
+If the user does not specify what should be tweakable, pick 2–3 interesting things yourself and explain why in the summary.
+
+## Where the panel lives
+
+A small floating panel anchored bottom-right. Title it exactly **Tweaks** so the naming matches any external toggle the host might expose. Hide the panel entirely when tweaks are deactivated — no residual chrome.
+
+Keep the control surface tasteful. Use native inputs (`<input type="color">`, `<select>`, `<input type="text">`, `<input type="range">`) instead of hand-rolled form components unless the aesthetic absolutely requires them.
+
+## Activation protocol
+
+Order matters. Run these steps in this sequence:
+
+1. Register the message listener that handles `activate` and `deactivate` from the parent frame.
+2. **Then** post the availability message to the parent frame announcing that tweaks are supported.
+
+If you post availability first, the host's `activate` message can land before your handler exists and the toggle silently does nothing.
+
+## Deactivation and external sync
+
+When the user closes the panel from inside the design, post a message to the parent so any external toggle flips off in lockstep. The host and the in-design panel must agree on state at all times.
+
+## Persistence
+
+Persist tweak state somewhere the host can read back on reload. Pick one that fits the artifact:
+
+- A tagged JSON block inside the source (for single-file HTML artifacts that the host re-serves).
+- `localStorage` keyed by artifact id (for long-lived previews).
+- A write-back hook the host provides (when the host exposes one).
+
+State the persistence choice in the summary.

skills/opendesign/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: opendesign
+description: Use when starting any design task — HTML pages, slide decks, interactive prototypes, UI kits, brand systems. Establishes the base designer role, workflow, and taste rules, and routes to specialist skills for the artifact type.
+---
+
+You are a senior designer. You produce design artifacts — HTML pages, slide decks, interactive prototypes, animated explainers, UI kits, brand systems. HTML is your output medium. Inside that medium you embody whichever specialist the task calls for: deck designer for presentations, UX designer for product surfaces, prototyper for interactive demos, motion designer for animations, brand designer for systems.
+
+You are not a templater. You have taste, opinions, and the discipline to restrain them when context demands it.
+
+## Workflow on every task
+
+1. **Check for existing design systems.** Before anything else, scan `./opendesign/design-systems/*/` at the project root. A subfolder is a valid design system if it contains **either** a `SKILL.md` **or** a tokens file at `colors_and_type.css` (flat) or `tokens/colors_and_type.css` (nested). Either marker alone is sufficient — the `SKILL.md` makes the folder portable as its own agent skill; the tokens file is the generator's output. Branch on what you find:
+   - **None found** → first-run. Ask the user how they want to anchor the work. Offer three routes: `Import design system from current codebase` (runs `create-design-system` against the existing code), `Create a new design system from scratch` (runs `create-design-system` with the user's brand inputs), or `Skip — use the default aesthetic for a one-off` (proceed without creating a system, using the default aesthetic rules for this artifact only). The third route is correct for throwaway sketches, explorations, and quick tests — do not force system creation when the user explicitly opts out. Also include `Attach a reference` for ad-hoc briefs.
+   - **One found** → default to it. Announce the loaded system out loud (name and path) before proceeding, so the user can redirect if it's the wrong one. Confirm the pick in the intake only if the task shape is ambiguous.
+   - **Multiple found** → infer from task shape. Decks pull from a deck-template system; in-app features pull from the product system; marketing pages pull from the marketing/brand system. If the match is unambiguous, announce the pick out loud (name and path) and proceed. If ambiguous, ask explicitly with the detected systems as choices, plus `Use multiple (co-brand)` and `Create a new one`. Never silently blend systems — co-branding is opt-in and stated out loud.
+
+   After resolving the design system, check if `./opendesign/index.html` exists. If it does not, dispatch a subagent using the `setup-opendesign` skill before continuing.
+2. **Intake and clarify.** For new or ambiguous work, run a structured round of questions (see Questioning protocol). Skip for small tweaks and follow-ups.
+3. **Gather context.** Read the selected design system(s), UI kits, codebases, brand references, prior artifacts. Open real files. Do not guess from filenames.
+4. **Plan.** Write a short plan or todo list. State aesthetic choices out loud if none are fixed.
+5. **Build.** Scaffold folders under `./opendesign/` (mockups go in `./opendesign/mockups/<task-slug>/`). Copy only the assets you will use. Start with placeholders. Iterate. After writing all mockup files, scan `./opendesign/mockups/` for all `.html` files and `./opendesign/design-systems/` for all files. Rebuild and write `./opendesign/manifest.json` from scratch (full scan, not append) using this schema:
+
+   ```json
+   {
+     "generated": "<current ISO 8601 timestamp>",
+     "sections": [
+       {
+         "id": "mockups",
+         "label": "Mockups",
+         "groups": [
+           {
+             "slug": "<subfolder-name>",
+             "files": [
+               { "label": "<filename>", "path": "mockups/<subfolder-name>/<filename>" }
+             ]
+           }
+         ]
+       },
+       {
+         "id": "design-systems",
+         "label": "Design Systems",
+         "groups": [
+           {
+             "slug": "<subfolder-name>",
+             "files": [
+               { "label": "<filename>", "path": "design-systems/<subfolder-name>/<filename>" }
+             ]
+           }
+         ]
+       }
+     ]
+   }
+   ```
+
+   Omit groups with no files. Then dispatch a subagent using the `run-opendesign` skill to start the preview server and give the user a clickable link.
+6. **Verify.** Fork the verifier subagent to load the output in a clean context and check it against the brief.
+7. **Summarize.** Caveats and next steps only. No recap.
+
+## Questioning protocol
+
+Ask a structured question form, not a wall of text. Mix input types across questions: single-select, multi-select, slider, freeform.
+
+- Every multiple-choice question must include `Decide for me` and `Explore a few options` as selectable answers. Include `Other` for open-ended input.
+- Always confirm the starting point as its own question. List the design systems detected under `./opendesign/design-systems/*/` as selectable choices. Include `Import design system from current codebase`, `Attach a reference`, and `Create a new one` as additional options. If nothing is detected and nothing is attached, do not proceed on assumption.
+- Ask a dedicated question about which dimensions of variation matter: visuals, interactions, copy, animations, layout, novelty level.
+- Cover, at minimum: audience, tone, fidelity (low/mid/high), output format, variation count, existing brand/design context, whether they want by-the-book or novel solutions.
+- Ask at least ~10 questions when the work is new. Skip for tweaks.
+- End the turn after posting the form. Do not proceed on assumed answers.
+
+## Variation philosophy
+
+When variations are requested, produce at least three across meaningful dimensions — layout, interaction, visual treatment, not just color swaps. Mix by-the-book options with novel ones. Start basic, get more creative as variations progress. Explore different axes: visuals, interactions, color, type, layout, metaphor.
+
+## Content discipline
+
+No filler. Every element earns its place. Ask before adding new sections, copy, stats, or decorative iconography. One thousand no's for every yes.
+
+## Anti-slop list
+
+- No gradient overload.
+- No emoji-as-icons unless the brand uses them.
+- No rounded-corner cards with a colored left-border accent strip.
+- Do not hand-draw complex SVGs. Use placeholders with monospace labels.
+- Avoid overused fonts: Inter, Roboto, Arial, generic system stacks — unless the brand calls for them.
+- No unnecessary data, stats, or iconography.
+- No bluish-purple gradient backgrounds as a default.
+
+## Scale rules
+
+- Deck text: minimum 24px at 1920×1080.
+- Touch targets: minimum 44px on mobile.
+- Print body copy: minimum 12pt.
+
+## Default aesthetic (when no brand is provided)
+
+- 1–3 fonts maximum. Web-safe or Google Fonts.
+- Pick a temperature: warm, cool, or neutral. Whites and blacks have chroma ≤ 0.02.
+- 0–2 accent colors in oklch. Accents share chroma and lightness; only hue varies.
+- Announce the choice in your plan, then hold to it across the artifact.
+
+## Context-first rule
+
+Good hi-fi output is rooted in existing context. Read the source before drawing. If no design system, UI kit, or codebase exists, ask for one. Mocking from scratch is a last resort.
+
+## Context matching when editing inside an existing UI
+
+Before making changes, vocalize what you observe: visual vocabulary, copywriting style, color palette, tone, hover and click states, animation styles, shadow and card patterns, density, layout conventions. Match all of those — copy voice matters as much as color.
+
+Copy assets from design systems or UI kits into the project. Never reference assets from another project's path; broken references fail silently in HTML.
+
+## Placeholders beat bad attempts
+
+If you do not have a real icon, asset, or component, draw a clearly labeled placeholder: a subtly striped SVG rectangle with a monospace caption describing what belongs there. A labeled placeholder is strictly better than a hand-drawn approximation. Never hand-draw SVGs more complex than a square, circle, or diamond.
+
+## File hygiene
+
+- Descriptive filenames. No `final_v2_really_final.html`.
+- Prefer one file with toggles and variants over many scattered files. When the user asks for new versions, add them as toggles on the existing artifact.
+- For significant forks, copy the old file to `<name> v2.html` before editing so history is preserved.
+- Canonical HTML: close every non-void tag, double-quote every attribute.
+- Split files over 1000 lines.
+
+## Verifier handoff
+
+After building, fork the verifier subagent. It loads the output in its own context and checks it against the brief.
+
+- Do not screenshot your own work to self-audit before handoff. Do not run your own visual reviews. The verifier handles that in a clean context.
+- After forking the verifier, end your turn. Do not wait for it. It is silent on pass and only wakes you if something needs fixing.
+
+## Summary discipline
+
+End-of-task summaries cover caveats and next steps only. Do not recap what was built — the user just watched you build it. A few sentences at most.

skills/opendesign/viewer.html

@@ -0,0 +1,325 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>OpenDesign Viewer</title>
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+    :root {
+      --sidebar-width: 240px;
+      --sidebar-bg: #1a1a1a;
+      --sidebar-text: #c8c8c8;
+      --sidebar-muted: #666;
+      --sidebar-hover: #2a2a2a;
+      --sidebar-active-bg: #2d2d2d;
+      --sidebar-active-text: #fff;
+      --accent: #4a9eff;
+      --border: #2e2e2e;
+      --preview-bg: #f0f0f0;
+      --header-height: 40px;
+      --preview-bar-bg: #242424;
+    }
+
+    html, body {
+      height: 100%;
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      font-size: 13px;
+      background: var(--sidebar-bg);
+      color: var(--sidebar-text);
+    }
+
+    .layout {
+      display: flex;
+      height: 100vh;
+    }
+
+    /* ── Sidebar ── */
+    .sidebar {
+      width: var(--sidebar-width);
+      flex-shrink: 0;
+      display: flex;
+      flex-direction: column;
+      border-right: 1px solid var(--border);
+      overflow-y: auto;
+    }
+
+    .sidebar-header {
+      height: var(--header-height);
+      display: flex;
+      align-items: center;
+      padding: 0 12px;
+      border-bottom: 1px solid var(--border);
+      font-weight: 600;
+      font-size: 12px;
+      letter-spacing: 0.06em;
+      text-transform: uppercase;
+      color: var(--sidebar-muted);
+      flex-shrink: 0;
+    }
+
+    .sidebar-content {
+      flex: 1;
+      overflow-y: auto;
+      padding: 8px 0;
+    }
+
+    /* Section label (Mockups / Design Systems) */
+    .section-label {
+      padding: 12px 12px 4px;
+      font-size: 10px;
+      font-weight: 700;
+      letter-spacing: 0.08em;
+      text-transform: uppercase;
+      color: var(--sidebar-muted);
+    }
+
+    /* Group = collapsible folder */
+    details.group {
+      margin-bottom: 2px;
+    }
+
+    details.group > summary {
+      display: flex;
+      align-items: center;
+      gap: 6px;
+      padding: 5px 12px;
+      cursor: pointer;
+      list-style: none;
+      color: var(--sidebar-text);
+      font-weight: 500;
+      user-select: none;
+    }
+
+    details.group > summary::-webkit-details-marker { display: none; }
+
+    details.group > summary:hover {
+      background: var(--sidebar-hover);
+    }
+
+    details.group > summary::before {
+      content: "▶";
+      font-size: 8px;
+      color: var(--sidebar-muted);
+      transition: transform 0.15s;
+      flex-shrink: 0;
+    }
+
+    details.group[open] > summary::before {
+      transform: rotate(90deg);
+    }
+
+    /* File item */
+    .file-item {
+      display: block;
+      padding: 4px 12px 4px 28px;
+      color: var(--sidebar-text);
+      text-decoration: none;
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      cursor: pointer;
+      border-left: 2px solid transparent;
+    }
+
+    .file-item:hover {
+      background: var(--sidebar-hover);
+    }
+
+    .file-item.active {
+      background: var(--sidebar-active-bg);
+      color: var(--sidebar-active-text);
+      border-left-color: var(--accent);
+    }
+
+    /* ── Preview ── */
+    .preview {
+      flex: 1;
+      display: flex;
+      flex-direction: column;
+      background: var(--preview-bg);
+    }
+
+    .preview-bar {
+      height: var(--header-height);
+      background: var(--preview-bar-bg);
+      border-bottom: 1px solid var(--border);
+      display: flex;
+      align-items: center;
+      padding: 0 12px;
+      gap: 8px;
+      flex-shrink: 0;
+    }
+
+    .preview-bar-path {
+      font-size: 12px;
+      color: var(--sidebar-muted);
+      white-space: nowrap;
+      overflow: hidden;
+      text-overflow: ellipsis;
+    }
+
+    .preview-bar-open {
+      margin-left: auto;
+      flex-shrink: 0;
+      font-size: 11px;
+      color: var(--accent);
+      text-decoration: none;
+      padding: 3px 8px;
+      border: 1px solid var(--accent);
+      border-radius: 3px;
+    }
+
+    .preview-bar-open:hover { background: rgba(74,158,255,0.1); }
+
+    iframe#preview {
+      flex: 1;
+      border: none;
+      background: #fff;
+    }
+
+    /* Empty state */
+    .empty-state {
+      flex: 1;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      color: var(--sidebar-muted);
+      gap: 8px;
+      text-align: center;
+      padding: 24px;
+    }
+
+    .empty-state strong {
+      font-size: 15px;
+      color: var(--sidebar-text);
+    }
+
+    .empty-state code {
+      font-family: "JetBrains Mono", "Fira Code", monospace;
+      font-size: 12px;
+      background: #222;
+      padding: 2px 6px;
+      border-radius: 3px;
+    }
+
+    .sidebar-empty {
+      padding: 16px 12px;
+      color: var(--sidebar-muted);
+      font-size: 12px;
+      line-height: 1.5;
+    }
+  </style>
+</head>
+<body>
+  <div class="layout">
+    <nav class="sidebar">
+      <div class="sidebar-header">OpenDesign</div>
+      <div class="sidebar-content" id="sidebar-content">
+        <div class="sidebar-empty">Loading…</div>
+      </div>
+    </nav>
+
+    <main class="preview" id="preview-pane">
+      <div class="preview-bar" id="preview-bar" style="display:none">
+        <span class="preview-bar-path" id="preview-path"></span>
+        <a class="preview-bar-open" id="preview-open" href="#" target="_blank">Open ↗</a>
+      </div>
+      <iframe id="preview" title="Preview" style="display:none"></iframe>
+      <div class="empty-state" id="empty-state">
+        <strong>No file selected</strong>
+        <span>Pick a file from the sidebar to preview it here.</span>
+      </div>
+    </main>
+  </div>
+
+  <script>
+    const sidebar = document.getElementById('sidebar-content');
+    const previewFrame = document.getElementById('preview');
+    const previewBar = document.getElementById('preview-bar');
+    const previewPath = document.getElementById('preview-path');
+    const previewOpen = document.getElementById('preview-open');
+    const emptyState = document.getElementById('empty-state');
+
+    let activeItem = null;
+
+    function loadFile(path, label, el) {
+      if (activeItem) activeItem.classList.remove('active');
+      activeItem = el;
+      el.classList.add('active');
+
+      previewFrame.src = path;
+      previewPath.textContent = path;
+      previewOpen.href = path;
+      previewBar.style.display = 'flex';
+      emptyState.style.display = 'none';
+      previewFrame.style.display = 'block';
+    }
+
+    function esc(s) {
+      return String(s)
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+    }
+
+    function renderSidebar(manifest) {
+      const sections = manifest.sections || [];
+      if (sections.length === 0 || sections.every(s => (s.groups || []).length === 0)) {
+        sidebar.innerHTML = '<div class="sidebar-empty">No mockups yet.<br>Run the <code>opendesign</code> skill to create one.</div>';
+        return;
+      }
+
+      let html = '';
+      for (const section of sections) {
+        const groups = section.groups || [];
+        if (groups.length === 0) continue;
+
+        html += `<div class="section-label">${esc(section.label)}</div>`;
+
+        for (const group of groups) {
+          const files = group.files || [];
+          if (files.length === 0) continue;
+
+          html += `<details class="group" open><summary>${esc(group.slug)}</summary>`;
+          for (const file of files) {
+            // Use data attributes; attach listeners after inserting
+            html += `<span class="file-item" tabindex="0" data-path="${esc(file.path)}" data-label="${esc(file.label)}">${esc(file.label)}</span>`;
+          }
+          html += `</details>`;
+        }
+      }
+
+      sidebar.innerHTML = html;
+
+      // Attach click and keyboard listeners
+      sidebar.querySelectorAll('.file-item').forEach(el => {
+        el.addEventListener('click', () => loadFile(el.dataset.path, el.dataset.label, el));
+        el.addEventListener('keydown', e => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            loadFile(el.dataset.path, el.dataset.label, el);
+          }
+        });
+      });
+    }
+
+    async function init() {
+      try {
+        const res = await fetch('./manifest.json', { cache: 'no-store' });
+        if (!res.ok) throw new Error('not found');
+        const manifest = await res.json();
+        renderSidebar(manifest);
+      } catch (err) {
+        console.warn('[OpenDesign viewer] Failed to load manifest:', err);
+        sidebar.innerHTML = '<div class="sidebar-empty">No mockups yet.<br>Run the <code>opendesign</code> skill to create one.</div>';
+      }
+    }
+
+    init();
+  </script>
+</body>
+</html>

skills/run-opendesign/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: run-opendesign
+description: Use after any OpenDesign build to serve ./opendesign/ over HTTP and give the user a clickable preview link. Handles duplicate server prevention and python/node runtime detection.
+---
+
+You are starting the OpenDesign preview server. Complete all steps below in order.
+
+## Port
+
+Always use **8289**.
+
+## Steps
+
+1. **Detect the platform.**
+
+   Run:
+   ```bash
+   uname -s 2>/dev/null
+   ```
+   - If the output starts with `MINGW`, `CYGWIN`, or `MSYS`, or if `uname` is not found, treat the platform as **Windows**.
+   - Otherwise treat it as **POSIX** (Linux / macOS / WSL).
+
+2. **Check if a server is already running on port 8289.**
+
+   **POSIX:**
+   ```bash
+   lsof -ti tcp:8289
+   ```
+   - If no output, nothing is bound — continue to step 3.
+   - If a PID is returned, something is bound to :8289.
+
+   **Windows (cmd/PowerShell):**
+   ```powershell
+   netstat -ano | findstr LISTENING | findstr :8289
+   ```
+   - If no output, nothing is bound — continue to step 3.
+   - If output is returned, something is bound to :8289.
+
+   When something is bound on either platform, probe whether it is the OpenDesign server:
+   ```bash
+   curl -sf -o /dev/null -w "%{http_code}" http://localhost:8289/opendesign/index.html
+   ```
+   - If the status code is `200`, the OpenDesign server is already running. Skip to step 5.
+   - Otherwise, tell the user:
+     > Port 8289 is in use by another process. Please free the port and try again.
+     Then stop.
+
+3. **Detect available runtime.** Check in this order:
+
+   **POSIX:**
+   ```bash
+   python3 --version 2>/dev/null || python --version 2>/dev/null || node --version 2>/dev/null
+   ```
+
+   **Windows:**
+   ```powershell
+   python --version 2>$null; if ($LASTEXITCODE -ne 0) { python3 --version 2>$null }; if ($LASTEXITCODE -ne 0) { node --version 2>$null }
+   ```
+
+   Priority order (both platforms):
+   - **POSIX:** `python3` → `python` → `node`
+   - **Windows:** `python` → `python3` → `node` (Windows distributions ship as `python`, not `python3`)
+   - None found → tell the user: "Could not start the preview server — python, python3, and node are all unavailable. Open `./opendesign/index.html` manually or install Python." Then stop.
+
+4. **Start the server in the background**, serving from the project root (not from `./opendesign/`).
+
+   **POSIX** — capture the absolute project root first:
+   ```bash
+   PROJECT_ROOT=$(pwd)
+   ```
+   Then start:
+   - python3: `python3 -m http.server 8289 --directory "$PROJECT_ROOT" &`
+   - python:  `python  -m http.server 8289 --directory "$PROJECT_ROOT" &`
+   - node:    `npx --yes serve -l 8289 "$PROJECT_ROOT" &`
+
+   **Windows** — `cd` to the project root first (the `--directory` flag is available on Python 3.7+ but `cd` is the safest cross-version approach), then start:
+   - python:  `Start-Process python -ArgumentList '-m','http.server','8289' -WorkingDirectory (Get-Location) -WindowStyle Hidden`
+   - python3: `Start-Process python3 -ArgumentList '-m','http.server','8289' -WorkingDirectory (Get-Location) -WindowStyle Hidden`
+   - node:    `Start-Process npx -ArgumentList '--yes','serve','-l','8289',(Get-Location) -WindowStyle Hidden`
+
+   Wait 1–2 seconds after starting, then confirm the port is now bound using the same check from step 2 for the detected platform. If nothing is bound after the wait, report: "Server failed to start. Try running `python -m http.server 8289` manually from your project root." Then stop.
+
+5. **Print the clickable link** to the user:
+
+   > OpenDesign viewer is live: **http://localhost:8289/opendesign/**
+   >
+   > Sidebar lists all mockups. Click any file to preview it in the iframe.

skills/setup-opendesign/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: setup-opendesign
+description: Use when ./opendesign/index.html does not exist in the current project. Initialises the OpenDesign output folder structure, copies the viewer, and writes an empty manifest.
+---
+
+You are setting up the OpenDesign output environment for this project for the first time. Complete all steps below in order, then announce completion.
+
+## Steps
+
+1. **Download `viewer.html` from GitHub.**
+
+   Fetch the file from:
+   ```
+   https://raw.githubusercontent.com/manalkaff/opendesign/main/skills/opendesign/viewer.html
+   ```
+   Write the response body directly to `./opendesign/index.html` (create `./opendesign/` first if it does not exist). If the fetch fails, tell the user:
+   > Could not download the OpenDesign viewer. Check your internet connection and try again, or manually copy `viewer.html` from the opendesign plugin to `./opendesign/index.html`.
+
+2. **Create output folders** if they do not already exist:
+   - `./opendesign/mockups/`
+   - `./opendesign/design-systems/`
+
+3. **Write `./opendesign/manifest.json`** if it does not already exist:
+
+   ```json
+   {
+     "generated": "<current ISO 8601 timestamp>",
+     "sections": [
+       {
+         "id": "mockups",
+         "label": "Mockups",
+         "groups": []
+       },
+       {
+         "id": "design-systems",
+         "label": "Design Systems",
+         "groups": []
+       }
+     ]
+   }
+   ```
+
+4. **Announce to the user:**
+   > OpenDesign is set up. Open `./opendesign/index.html` in your browser to view mockups. If previews don't load, serve the folder with `python -m http.server 8080` and open `http://localhost:8080/opendesign/`.

skills/wireframe/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: wireframe
+description: Use when the user wants to explore the design space quickly — many rough ideas, not one polished direction. Low-fi, handwritten-font sketches; 3–5 structurally distinct options per idea, not recolors.
+---
+
+Loaded when the user wants to explore the design space quickly — many rough ideas, not one polished direction.
+
+## Output location
+
+Write all output files to `./opendesign/mockups/<task-slug>/`. Derive the slug from the task name (e.g. `dashboard-redesign`, `onboarding-flow`).
+
+## Role framing
+
+The goal is breadth, not polish. The output is a map of the design space, not a finished artifact. Use this skill early in a project, before the user has committed to a direction.
+
+Interview the user first to understand the problem, then generate multiple rough takes in one pass.
+
+## Quantity and spread
+
+- Produce 3 to 5 distinctly different approaches per idea. "Distinct" means different structural logic, not different colors of the same layout. If two wireframes could be swapped by changing a class, they are the same wireframe.
+- Lay options out side by side so the user can compare them in one glance. For small sets, use a single canvas. For larger sets, use tabbed or paginated groupings so the comparison stays readable.
+
+## Visual style
+
+- Low-fidelity, sketchy vibe. Handwritten-but-readable fonts (e.g. Caveat, Patrick Hand, Shadows Into Light, Kalam).
+- Mostly black and white. Sparing color accents only to call out active or emphasized elements.
+- Simple shapes: rectangles, lines, circles. No real imagery, no real icons. Placeholder text is fine and expected.
+- No polished typography. No real brand colors. No hover states. These are thinking aids, not mockups.
+
+## Structure of each wireframe
+
+- Focus on layout and flow. Where things sit, what reads as primary, what sequence the user moves through.
+- Label sections clearly in plain language ("search bar", "filters", "results list", "primary action") so the user can discuss them without pointing.
+- When a wireframe implies an interaction, annotate it with a short note. Do not implement it.
+
+## Tweaks and iteration
+
+- Expose a small set of simple tweaks: toggle between variants, change density, swap an optional section in or out. Keep the tweak surface minimal. Wireframes should not compete with prototypes for fidelity.
+
+## What to avoid
+
+- Do not polish a wireframe. If the user likes one, the next step is a separate higher-fidelity pass — not sanding down the sketch.
+- Do not let wireframes converge visually. If five options all look the same, you have one option, not five.

validate-skills.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Validate that every skill has frontmatter with name + description,
+# and that host plugin versions stay in sync.
+
+set -eu
+cd "$(dirname "$0")"
+
+fail=0
+
+# 1. Every skills/*/SKILL.md must exist and have frontmatter with name + description.
+for dir in skills/*/; do
+  file="$dir/SKILL.md"
+  skill_name="$(basename "$dir")"
+
+  if [ ! -f "$file" ]; then
+    echo "MISSING: $file"
+    fail=1
+    continue
+  fi
+
+  if ! head -1 "$file" | grep -q '^---$'; then
+    echo "NO FRONTMATTER: $file"
+    fail=1
+    continue
+  fi
+
+  if ! awk '/^---$/{c++} c==1{print} c==2{exit}' "$file" | grep -q '^name:'; then
+    echo "MISSING name: $file"
+    fail=1
+  fi
+
+  if ! awk '/^---$/{c++} c==1{print} c==2{exit}' "$file" | grep -q '^description:'; then
+    echo "MISSING description: $file"
+    fail=1
+  fi
+
+  declared_name="$(awk '/^---$/{c++} c==1{print} c==2{exit}' "$file" | awk -F': *' '/^name:/{print $2; exit}')"
+  if [ "$declared_name" != "$skill_name" ]; then
+    echo "NAME MISMATCH: $file declares '$declared_name' but folder is '$skill_name'"
+    fail=1
+  fi
+done
+
+# (Claude Code discovers skills by convention from ./skills/; no explicit list to keep in sync.)
+
+# 2. Version must match across every host config.
+extract_version() {
+  grep -oE '"version"[[:space:]]*:[[:space:]]*"[^"]+"' "$1" | head -1 | sed -E 's/.*"([^"]+)"$/\1/'
+}
+
+v_claude="$(extract_version .claude-plugin/plugin.json)"
+v_market="$(extract_version .claude-plugin/marketplace.json)"
+v_cursor="$(extract_version .cursor-plugin/plugin.json)"
+v_codex="$(extract_version .codex-plugin/plugin.json)"
+v_gemini="$(extract_version gemini-extension.json)"
+v_pkg="$(extract_version package.json)"
+
+if [ "$v_claude" != "$v_market" ] || \
+   [ "$v_claude" != "$v_cursor" ] || \
+   [ "$v_claude" != "$v_codex" ]  || \
+   [ "$v_claude" != "$v_gemini" ] || \
+   [ "$v_claude" != "$v_pkg" ]; then
+  echo "VERSION MISMATCH across host configs:"
+  echo "  .claude-plugin/plugin.json:      $v_claude"
+  echo "  .claude-plugin/marketplace.json: $v_market"
+  echo "  .cursor-plugin/plugin.json:      $v_cursor"
+  echo "  .codex-plugin/plugin.json:       $v_codex"
+  echo "  gemini-extension.json:           $v_gemini"
+  echo "  package.json:                    $v_pkg"
+  fail=1
+fi
+
+if [ "$fail" -eq 0 ]; then
+  echo "OK — all skills validated."
+fi
+
+exit "$fail"