From c7d6c8e92e7197ee3e27b6c2f976fcae15e75593 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Sat, 6 Jun 2026 03:46:26 +0000 Subject: [PATCH] chore: sync skills from openai/plugins --- skills/magicpath/SKILL.md | 144 ++++++++++++++++++ skills/magicpath/references/cli-reference.md | 96 ++++++++++++ .../working-with-embedded-browsers.md | 54 +++++++ .../references/working-with-repositories.md | 71 +++++++++ skills/setup-metabase-instance/SKILL.md | 6 +- skills/setup-metabase-mcp/SKILL.md | 94 ------------ skills/setup-metabase-mcp/agents/openai.yaml | 4 - 7 files changed, 368 insertions(+), 101 deletions(-) create mode 100644 skills/magicpath/SKILL.md create mode 100644 skills/magicpath/references/cli-reference.md create mode 100644 skills/magicpath/references/working-with-embedded-browsers.md create mode 100644 skills/magicpath/references/working-with-repositories.md delete mode 100644 skills/setup-metabase-mcp/SKILL.md delete mode 100644 skills/setup-metabase-mcp/agents/openai.yaml diff --git a/skills/magicpath/SKILL.md b/skills/magicpath/SKILL.md new file mode 100644 index 0000000..0d976f4 --- /dev/null +++ b/skills/magicpath/SKILL.md @@ -0,0 +1,144 @@ +--- +name: magicpath +description: Use when the user mentions MagicPath, designs, UI components, themes, canvas selections, or repo-to-canvas UI work; run magicpath-ai to search, inspect, install, or author components. +allowed-tools: Bash(npx -y magicpath-ai *) +user-invocable: true +--- + +# MagicPath + +MagicPath is a canvas and component platform. Use this skill when the user mentions MagicPath, designs, UI components, themes/design systems, team projects, selected canvas items, or bringing local/repository UI into a MagicPath canvas. + +Always run MagicPath CLI commands as: + +```bash +npx -y magicpath-ai -o json +``` + +Use JSON output for data-returning commands and `-y` for non-interactive installs. + +## First Step + +Run: + +```bash +npx -y magicpath-ai info -o json +``` + +If the user is not authenticated, run: + +```bash +npx -y magicpath-ai login +npx -y magicpath-ai whoami -o json +``` + +## Pick the Workflow + +- Find or install a MagicPath component: search/list, confirm the right component, inspect it, then add/adapt it. +- Work with the current canvas: use `selection -o json` for selected components/images, or `active-project -o json` for the open project. +- Use team work: run `list-teams -o json`, then pass `--team ""` to project, search, theme, or member commands. +- Use a theme/design system: `list-themes -o json`, then `get-theme -o json`; apply CSS variables, fonts, and prompt guidance in the target app. +- Create or edit canvas components from code: use `code start`, edit only allowed files, then `code submit --wait`. +- Bring an existing repo UI into MagicPath: follow [Working with repositories](references/working-with-repositories.md). +- Keep a MagicPath project open inside Codex's Browser when doing canvas work: follow [Working with embedded browsers](references/working-with-embedded-browsers.md). + +## Find and Confirm Components + +1. If the user refers to a selected design/component/image, run `selection -o json`. +2. If the user refers to the project they have open, run `active-project -o json`. +3. Otherwise search or browse: + +```bash +npx -y magicpath-ai search "button" -o json +npx -y magicpath-ai list-projects -o json +npx -y magicpath-ai list-components -o json +``` + +Search/list results include `generatedName`, project context, owner fields, and often `previewImageUrl`. Use previews when visual context matters. + +Stop and ask for confirmation before installing or editing unless the user gave an exact `generatedName`, selected canvas item, or component/project id. + +## Install Into an App + +Use this when MagicPath is the source and the user's app is the destination. + +1. Inspect first: + +```bash +npx -y magicpath-ai inspect -o json +``` + +2. Read the target code before installing. Understand current props, callbacks, validation, layout, data flow, styling system, and accessibility behavior. +3. For React/TypeScript apps, install: + +```bash +npx -y magicpath-ai add -y -o json +``` + +4. Import and render the installed component using the returned `importStatement` and `usage`. +5. Adapt the installed source in `src/components/magicpath//`: + - Replace static text and mock data with props or real project data. + - Wire events, loading, error, empty, disabled, focus, and keyboard states. + - Make fixed dimensions responsive. + - Preserve existing behavior when replacing an existing component. + - Match the app's styling and state-management patterns. + +Do not run `add` just to read code. Use `inspect` for read-only source. For non-JS projects, inspect and translate the design into the target framework instead of running `add`. + +## Create or Edit Canvas Components + +Use this when the MagicPath canvas is the destination. + +```bash +npx -y magicpath-ai code start --project --dir --name "Component Name" --width --height -o json +npx -y magicpath-ai code start --component --dir -o json +npx -y magicpath-ai code submit --dir --wait -o json +``` + +Rules for `code` work: + +- Run `code start` before writing files so the canvas shows the pending work. +- Edit only `src/App.tsx`, `src/index.css`, `src/components/generated/**`, and temporary image assets under `assets/**`. +- Usually leave `src/App.tsx` alone except for the theme value. +- Put real implementation in `src/components/generated/.tsx`; split larger pieces into sibling files there. +- Use Tailwind v4 through `src/index.css`; do not add `tailwind.config.js`. +- Keep output responsive, centered, and free of device/browser mockups unless explicitly requested. +- Build one screen per component. For related multi-view flows, use local React state inside one component; for independent screens, create separate components in separate workdirs. +- Make interactive surfaces actually interactive: controlled inputs, real handlers, toggles, tabs, dialogs, form validation, hover/focus/disabled states, and useful transitions. +- If selected canvas images are returned by `code start`, use the downloaded `assetPath`, not the short-lived `accessUrl`. +- If `code submit` fails, fix only allowed files and resubmit. + +`code context` is read-only. Do not use it as the submit path. + +## Teams, People, and Ownership + +- `list-teams -o json`: discover teams/workspaces. +- `list-members --team "" -o json`: resolve people to user ids. +- `list-projects --team "" -o json`: see team projects only. +- `list-components --created-by -o json`: find work by a person in a team project. + +Personal projects are private to their owner unless shared. Do not search another person's personal work; search team projects instead. + +## Project and Share Links + +Use `share` when you need a URL without opening a browser: + +```bash +npx -y magicpath-ai share -o json +npx -y magicpath-ai share -o json +``` + +Use `view` only when intentionally opening the OS browser: + +```bash +npx -y magicpath-ai view +npx -y magicpath-ai view +``` + +Never run `view` commands in parallel. + +## References + +- [CLI reference](references/cli-reference.md) +- [Working with repositories](references/working-with-repositories.md) +- [Working with embedded browsers](references/working-with-embedded-browsers.md) diff --git a/skills/magicpath/references/cli-reference.md b/skills/magicpath/references/cli-reference.md new file mode 100644 index 0000000..d609363 --- /dev/null +++ b/skills/magicpath/references/cli-reference.md @@ -0,0 +1,96 @@ +# MagicPath CLI Reference + +Run commands through `npx -y magicpath-ai`. Prefer `-o json` for structured output and `-y` for non-interactive installs. + +## Auth and Context + +```bash +npx -y magicpath-ai info -o json +npx -y magicpath-ai login +npx -y magicpath-ai whoami -o json +``` + +`info` returns auth state, user context, teams, projects, and CLI version. + +## Discovery + +```bash +npx -y magicpath-ai search "query" -o json +npx -y magicpath-ai search "query" --team "Acme" -o json +npx -y magicpath-ai search "query" --personal -o json +npx -y magicpath-ai list-projects -o json +npx -y magicpath-ai list-components -o json +``` + +Useful flags: `--limit`, `--offset`, `--after`, `--sort-by name|createdAt`, `--order asc|desc`, `--team `, `--personal`, and `--created-by `. + +Results may include `ownerType`, `ownerName`, `createdBy`, `lastEditedBy`, `generatedName`, and `previewImageUrl`. + +## Teams and People + +```bash +npx -y magicpath-ai list-teams -o json +npx -y magicpath-ai list-members --team "Acme" -o json +``` + +Use member ids with `list-components --created-by -o json`. + +## Themes + +```bash +npx -y magicpath-ai list-themes -o json +npx -y magicpath-ai list-themes --team "Acme" -o json +npx -y magicpath-ai get-theme -o json +npx -y magicpath-ai get-theme "Brand" --team "Acme" -o json +``` + +Theme output can include light/dark CSS variables, default theme, fonts, and a natural-language styling prompt. + +## Inspect, Install, Share, and View + +```bash +npx -y magicpath-ai inspect -o json +npx -y magicpath-ai add -y -o json +npx -y magicpath-ai add --dry-run -o json +npx -y magicpath-ai share -o json +npx -y magicpath-ai share -o json +npx -y magicpath-ai view +npx -y magicpath-ai view +``` + +`inspect` reads source without writing files. `add` installs React/TypeScript source into the current app. `share` returns a URL without browser navigation. `view` opens the browser and should not be parallelized. + +## Canvas Context and Images + +```bash +npx -y magicpath-ai selection -o json +npx -y magicpath-ai active-project -o json +npx -y magicpath-ai image list -o json +npx -y magicpath-ai image add ./image.png -o json +``` + +Use `selection` for selected components/images. Use `active-project` when the user says "this project" or "the project I have open." + +## Create Projects + +```bash +npx -y magicpath-ai create-project --name "My Project" -o json +npx -y magicpath-ai create-project --name "My Project" --team "Acme" -o json +``` + +If the user has teams and does not say personal or team, ask which workspace before creating. + +## Author or Edit Canvas Components + +```bash +npx -y magicpath-ai code start --project --dir --name "Name" --width --height -o json +npx -y magicpath-ai code start --component --dir -o json +npx -y magicpath-ai code start --component --revision --dir -o json +npx -y magicpath-ai code context --dir -o json +npx -y magicpath-ai code submit --dir --width --height --wait -o json +npx -y magicpath-ai code status -o json +``` + +`code start` begins a stateful authoring session and writes scaffold files. `code submit` publishes edits back to the canvas. `code context` is read-only. + +Editable files in a code workdir are limited to `src/App.tsx`, `src/index.css`, `src/components/generated/**`, and temporary `assets/**`. diff --git a/skills/magicpath/references/working-with-embedded-browsers.md b/skills/magicpath/references/working-with-embedded-browsers.md new file mode 100644 index 0000000..750778b --- /dev/null +++ b/skills/magicpath/references/working-with-embedded-browsers.md @@ -0,0 +1,54 @@ +# Working With Embedded Browsers + +Use this when the host exposes an embedded browser, such as Codex's Browser capability, and the user is creating, editing, reviewing, or selecting work on a MagicPath project canvas. + +Keep the embedded browser on the project canvas. Do not navigate it to individual component previews unless the user explicitly asks. + +## Open a Project Canvas + +Do not use `view ` when you want an embedded browser URL; `view` opens the operating-system browser. Get the project URL instead: + +```bash +npx -y magicpath-ai share -o json +``` + +Navigate the embedded browser to the returned `url`. + +## New Project Flow + +1. Create the project: + +```bash +npx -y magicpath-ai create-project --name "Name" -o json +``` + +2. Run `share -o json`. +3. Open the returned project URL in the embedded browser. +4. Start canvas authoring with `code start`. +5. Keep the browser on that project while submitting and reviewing. + +If the embedded browser redirects to sign-in or home, tell the user to sign in there, then navigate back to the same project URL. CLI auth and browser auth are separate. + +## Existing Project Flow + +If the user refers to the open project, run: + +```bash +npx -y magicpath-ai active-project -o json +``` + +If one project is returned, open its shared URL if it is not already visible. If multiple or none are returned, ask which project. + +Use: + +```bash +npx -y magicpath-ai selection -o json +``` + +when the user refers to selected canvas components or images. + +## Quiet Operations + +Do not navigate the browser for background commands like `info`, `whoami`, `list-projects`, `list-components`, `list-teams`, `search`, `list-themes`, `get-theme`, `inspect`, `add`, or polling build status. + +Return a component share link with `share -o json` when the user asks for a link. Navigate to that component only when they ask to open or view that specific design. diff --git a/skills/magicpath/references/working-with-repositories.md b/skills/magicpath/references/working-with-repositories.md new file mode 100644 index 0000000..d779f8c --- /dev/null +++ b/skills/magicpath/references/working-with-repositories.md @@ -0,0 +1,71 @@ +# Working With Repositories + +Use this when the user wants existing UI from a local path or Git repository recreated on the MagicPath canvas. This is the inverse of `add`/`inspect`: the source is the repo, and the destination is a new or edited MagicPath canvas component. + +Do not use `add`, `inspect`, or `code context` for this workflow. + +## 1. Get the Code + +- Local repo: read the path directly after confirming the target if ambiguous. +- Online repo: clone shallowly into scratch space, separate from the MagicPath `--dir`. +- Private repo: ask for access or a local checkout if clone fails; do not guess credentials. +- Monorepo: identify the relevant app/package before reading deeply. + +## 2. Read the Design Foundation + +Before building, inspect: + +- Framework and dependencies from `package.json`. +- Global CSS such as `globals.css`, `index.css`, `app.css`, or `styles/**`. +- Design tokens: CSS variables, theme files, `tailwind.config.*`, color/font/radius/shadow values. +- Font loading strategy. +- Light/dark theme handling. +- Shared primitives such as `components/ui`, icons, buttons, cards, and layout shells. + +## 3. Resolve the Target + +For one component, trace the component file, child imports, constants/data, CSS, icons, assets, and the parent layout that gives it size and position. + +For a page or whole project, identify the route/page entry and walk the component tree. If the user did not specify the page, ask one short question and stop. + +Use one MagicPath component for one cohesive interactive screen or flow. Use separate components/workdirs for genuinely independent screens. + +## 4. Plan the Canvas Build + +- Choose useful `--width` and `--height` values, such as `1440x900` for desktop or `390x844` for mobile. +- Translate the repo's styling into React + Tailwind v4 in MagicPath's generated structure. +- Convert CSS variables into `src/index.css` and reference them from classes or CSS. +- Copy real image assets into `/assets/`; do not hotlink repo blob URLs or inline base64. +- For Vue, Svelte, Angular, SwiftUI, or plain HTML, reproduce the visual output and behavior in React rather than copying framework syntax. + +## 5. Build and Submit + +Start before editing so the canvas shows a pending component: + +```bash +npx -y magicpath-ai code start --project --dir --name "Name" --width --height -o json +``` + +Then edit only: + +- `src/App.tsx` +- `src/index.css` +- `src/components/generated/**` +- `assets/**` + +Submit and wait: + +```bash +npx -y magicpath-ai code submit --dir --width --height --wait -o json +``` + +If build diagnostics return, fix allowed files and resubmit. Do not start a new component to avoid a fixable failure. + +## Fidelity Rules + +- Match the source UI's colors, spacing, radii, typography, shadows, and behavior. +- Keep the component responsive and centered. +- Do not add phone/browser/device frames unless explicitly requested. +- Use local mock data for backend-driven content. +- Wire real state for tabs, drawers, forms, menus, active nav items, and multi-step flows. +- Keep a single frame for one screen; use internal state for navigation within a cohesive flow. diff --git a/skills/setup-metabase-instance/SKILL.md b/skills/setup-metabase-instance/SKILL.md index 633883c..6b7043e 100644 --- a/skills/setup-metabase-instance/SKILL.md +++ b/skills/setup-metabase-instance/SKILL.md @@ -282,7 +282,7 @@ Once healthy, tell the user: ## Required: Initialize Metabase -**You MUST run the gates below in order. Do NOT invoke `setup-metabase-mcp`, do NOT start the app-backed OAuth flow, and do NOT report "Metabase is ready" until every gate passes.** Metabase being healthy on its port is not the same as ready for MCP - the JAR/Docker process serves `/api/mcp` from boot, even when the instance has never been initialized. Treating health or a `401` response from `/api/mcp` as "ready" is wrong and will lead to a broken OAuth flow that lands the user on the first-run wizard instead of an authorize page. **This has happened before. Do not do it.** +**You MUST run the gates below in order. Do NOT report "Metabase is ready" until every gate passes.** Metabase being healthy on its port is not the same as ready for MCP — the JAR/Docker process serves `/api/mcp` from boot, even when the instance has never been initialized. Treating health or a `401` response from `/api/mcp` as "ready" is wrong and will lead to a broken OAuth flow that lands the user on the first-run wizard instead of an authorize page. **This has happened before. Do not do it.** **Never automate Metabase configuration via REST.** Do **not** call any of these endpoints: @@ -385,9 +385,9 @@ This gate completes on the user's confirmation when they reply "done" / "added" Continue immediately to Gate 3. -### Gate 3 - Hand back to MCP setup +### Gate 3 — Confirm and stop -Only after Gates 1 and 2 are both resolved, resume the `setup-metabase-mcp` skill with `http://localhost:$PORT` as the instance URL. Do not ask the user for the URL again, you already know it. That skill validates the URL (version + MCP endpoint) and hands the user to the app-backed connection flow. Do not duplicate those checks here, do not edit `.app.json`, and do not create `.mcp.json`. +Only after Gates 1 and 2 are both resolved, confirm to the user that Metabase is ready at `http://localhost:$PORT` (substitute the actual port) and stop. --- diff --git a/skills/setup-metabase-mcp/SKILL.md b/skills/setup-metabase-mcp/SKILL.md deleted file mode 100644 index 5704411..0000000 --- a/skills/setup-metabase-mcp/SKILL.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -name: setup-metabase-mcp -description: Read these instructions before using Metabase MCP tools. Setup is needed to connect to Metabase instances through the Metabase app-backed connector. ---- - -**Read this entire skill file end-to-end before taking any action.** Do not skim, do not stop at the first matching step, and do not act on the summary alone. The gates, failure modes, prohibitions, and post-setup rules are scattered through the document. - -**Follow these instructions exactly as written.** Do not make assumptions, do not silently substitute "equivalent" actions, and do not bypass the app-backed connector flow. If a step says stop, stop. - ---- - -Configure the Metabase Codex plugin so the user can connect to a ready Metabase instance through the Metabase app-backed connector. This skill assumes the instance itself is already set up and has the MCP feature enabled - that is the job of the `setup-metabase-instance` skill, not this one. - -The plugin is app-backed. `../../.app.json` is a static app mapping, not a per-user runtime config file. Do not rewrite `.app.json` with the user's Metabase URL, and do not create or restore `.mcp.json` as a workaround. - -## Valid Instance URL Formats - -- Local development: `http://localhost:3000` -- Metabase Cloud: `https://yourcompany.metabaseapp.com` -- Self-hosted: `https://metabase.yourcompany.com` - -## Required Actions - -1. Read `../../.app.json` (relative to this `SKILL.md` - two directories up, the plugin root). It must contain a Metabase app entry with a non-empty app or connector ID. - - Expected shape: - - ```json - { - "apps": { - "metabase": { - "id": "templated_apps_6a044bbd332881919b553bdfc2240952" - } - } - } - ``` - - If `apps` is empty or there is no `metabase` entry, stop and tell the user: - - > This Metabase plugin is missing its Codex app mapping. Ask the plugin maintainer to add the Metabase app or connector ID to `.app.json`, reinstall the plugin, and start a new chat. - - Do not continue, do not edit `.app.json`, and do not run `codex mcp login`. - -2. Stop all other exploration. Ask the user: "Do you have a Metabase instance URL, or would you like to set up a local instance?" - - - **If they provide a URL**: continue with step 3. - - **If they don't have one and want to set up a local instance**: invoke the `setup-metabase-instance` skill. That skill spins up Metabase, walks the user through first-run setup, and returns with a ready URL (typically `http://localhost:3000`). Continue here with that URL. - -3. Sanity-check that the URL points at a **ready-to-use** Metabase instance. Run all three probes: - - ```bash - curl -s /api/session/properties | grep -o '"tag":"[^"]*"' - curl -s /api/session/properties | grep -o '"has-user-setup":[a-z]*' - curl -s -o /dev/null -w "%{http_code}\n" /api/mcp - ``` - - All three must pass: - - - Version tag's major version is **>= 60**. - - `"has-user-setup":true` - instance has an admin account and is past the first-run wizard. - - `/api/mcp` response code is **`401`** - endpoint live, OAuth required. - - If any fails, **stop**. Do not run OAuth and do not modify plugin files. Failure modes: - - - **`has-user-setup:false`** - the instance is running but has never been initialized. If this is the local instance launched through this workflow, forward to the `setup-metabase-instance` skill so its Gate 1 walks the user through the first-run wizard. If this is a user-supplied Cloud or self-hosted URL, tell the user to open `` in their browser, complete the first-run wizard there, and then come back so you can re-run step 3 here. - - **Version < 60** - tell the user to upgrade Metabase, then stop. - - **`/api/mcp` returns `404`** - MCP is on by default in 60+ and has no toggle, so this usually means the version is older than reported or the URL is wrong. Ask the user to confirm. - - **Other HTTP codes** - surface the code to the user and stop. - - **Never call `POST /api/setup`, `POST /api/session`, or any other authenticated Metabase REST endpoint.** Those bypass the OAuth flow this skill depends on. If the user asks you to, refuse. - -4. Hand the user to the app-backed connection flow. Tell them: - - > Your Metabase instance is ready. Connect the Metabase app in Codex using this URL: ``. Complete the OAuth approval in Metabase, then start a new chat so the app tools are available. - - Do not run `codex mcp login`. This plugin no longer registers a local `.mcp.json` MCP server; authentication belongs to the Codex app connector. - -5. Tell the user to start a new chat so the app config and token take effect: - - - **Codex CLI**: `/new` - - **Codex Desktop**: click **New chat** in the sidebar - - Confirm setup is complete and **stop**. The Metabase tools become available in the new thread. - -## After setup: do NOT bypass MCP - -Once the app connector is configured, the **only** way to read data from Metabase is through the Metabase app/MCP tools. Do not, under any circumstances: - -- Read, copy, snapshot, or query Metabase's H2 application database file directly (`metabase.db`, `metabase.db.mv.db`, `metabase.db.h2.db`, etc.). Even read-only inspection or working from a copy is forbidden. -- Use `sqlite`, `duckdb`, `h2`, JDBC, JDBC tools, Python `sqlalchemy`/`h2`/`jaydebeapi`, or any other client to talk to Metabase's storage. -- Call Metabase REST endpoints (`/api/card`, `/api/dashboard`, `/api/database`, `/api/session`, etc.) to answer the user's question while the new chat is pending. -- Run any other side-channel that bypasses the configured app/MCP server. - -If the running chat does not yet expose Metabase tools, the correct response is only to remind the user to start a new chat and stop. Do not offer to inspect internals. diff --git a/skills/setup-metabase-mcp/agents/openai.yaml b/skills/setup-metabase-mcp/agents/openai.yaml deleted file mode 100644 index 9ec7839..0000000 --- a/skills/setup-metabase-mcp/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Set Up Metabase MCP" - short_description: "Connect Codex to a ready Metabase instance" - default_prompt: "Use $setup-metabase-mcp to connect Codex to my Metabase instance."