Use MagicPath through the magicpath-ai CLI to find, preview, inspect, install, export, create, and edit UI components and manage MagicPath skills. Trigger for MagicPath designs/components; personal or team projects; active canvases and selected components/images/revisions; themes/design systems; tea

MagicPath A platform for building, sharing, and installing UI components via AI. Components are added as source code to the user's project via the magicpath ai CLI. MagicPath canvas components can also be created and edited directly from local code via the npx y magicpath ai code ... subcommands — see [Edit or create canvas components from code]( edit or create canvas components from code). That path is strict: only src/App.tsx , src/index.css , files under src/components/generated/ , and temporary image assets under assets/ in the code working directory are editable. When this skill runs inside an agent host with an embedded browser, use a MagicPath project as a persistent visual canvas beside the agent when appropriate. If you create a project for canvas authoring, open that project in the embedded browser immediately after creation and before code start ; see [Working with embedded browsers](references/working with embedded browsers.md). Terminology: Users often refer to MagicPath components as "designs" — the two terms are interchangeable. When a user says "design," "my designs," or "that design," treat it as meaning a MagicPath component. Search, inspect, and install accordingly. Users also refer to MagicPath design systems as "themes." When a user says "theme," "my themes," or "use the X theme," they mean a MagicPath design system — a set of CSS variables, fonts, and styling instructions. Use list themes and get theme to work with them. Users may belong to teams (also called "workspaces"). When a user says "the team's designs," "our team's components," or mentions a team name like "Acme Inc," they mean the projects and components owned by that team. Use list teams , team , and personal flags to navigate between personal and team workspaces. Users may also ask about skills they created in MagicPath. These are reusable instruction bundles that can be invoked from MagicPath chat and managed with npx y magicpath ai skills ... . Personal skills live in the user's workspace; team skills live in a MagicPath team. Public MagicPath skills are read only unless the platform says otherwise. First Step Run npx y magicpath ai info o json to check auth status and project context. The first invocation may take a few seconds as npx downloads the package; subsequent calls are fast. If auth.authenticated is false, run npx y magicpath ai login , wait for browser auth to finish, then verify with npx y magicpath ai whoami o json . Guest Sessions If the user gives you a pairing code (a short code like gst … , usually because they're trying MagicPath without an account), connect with it once: Then run npx y magicpath ai whoami o json — it reports guest: true , the one projectId you can work with, and a canvasUrl . Build on that project with the normal code start project <projectId → code submit flow; every submit appears live on the canvas. A guest session is scoped to that single project and expires. Within it: Use code start / code submit to create and edit designs on the project — this is the whole point of the session. In a host with an embedded browser, open the canvasUrl (from whoami ) so the user can watch their canvas update beside you. The canvasUrl is the only way to open a guest canvas — do not use share or view , which require a full account. Other workspace features (teams, additional projects, themes) belong to full accounts. If a command reports it needs an account, tell the user to sign up from the canvas open in their browser — that's what saves this project to their account and unlocks everything else. (If their session has already expired, the project can't be saved and they'd start fresh.) Never tell a guest to run login without a pairing code. Working with Teams Users may belong to teams that own shared projects and themes. By default, list projects and search return results from all workspaces (personal + every team the user belongs to). Use filtering flags to narrow scope. Discovering Teams Run npx y magicpath ai list teams o json to see the user's teams: Filtering by Team Default (no flag) : list projects , search include both personal and all team projects — no extra flags needed for broad discovery. team "Acme Inc" or team <teamId : Filter to a specific team. Works on list projects , search , list themes , and get theme . personal : Show only the user's personal projects/components. Works on list projects and search . JSON Output Projects and search results include ownerType ( "personal" or "team" ) and ownerName (user email or team name). Use these to tell the user where a component lives. Discovering People Run npx y magicpath ai list members team "Acme Inc" o json to see who's on a team: Filtering by Person created by <userId on list components : Filter to components that a specific user has created or edited. Use this after resolving a person's name to their user ID via list members . createdBy field on projects: Each project in list projects includes createdBy: { id, displayName } showing who created it. lastEditedBy field on components: Each component in list components includes lastEditedBy: { id, displayName } showing who last edited it. Important: You can only see projects that the authenticated user has access to — your own personal projects and team projects you're a member of. You cannot access another user's personal projects. When looking for another person's work, only search team projects ( team ), not personal projects. Personal projects are private to their owner unless someone is explicitly invited as a member. Common Patterns "What was Chloe working on last?" → list members team "Acme Inc" o json to find Chloe's user ID → list projects team "Acme Inc" o json to get team projects only → list components <projectId created by <chloeId sort by createdAt order desc o json for each project. Report the most recent components. Do not search personal projects for another user's work — personal projects are private to their owner. "Show me the team's designs" or "what has Acme Inc created?" → list teams to find the team, then list projects team "Acme Inc" o json , then list components <projectId o json . "Show me the latest design from the team" → same as above, but use sort by createdAt order desc limit 1 on list components . "Who created this project/component?" → check the createdBy field on projects or the lastEditedBy field on components from their respective list commands. "My designs" without mentioning a team → the default (all projects) is usually correct. Only use personal if they explicitly want to exclude team projects. "Use the team's theme" → list themes team "Acme Inc" o json , then get theme <name team "Acme Inc" o json . Managing MagicPath Skills Use this flow when the user asks to create, list, inspect, update, import, delete, enable/disable, or locally install skills stored in MagicPath. Prefer JSON mode for every data returning command: Scope and Ownership Use team <nameOrId when the user says the skill belongs to a team/workspace. Omit team for personal skills. skills list includes public MagicPath skills by default because those are available to the user in chat. Pass owned only when the user wants skills they can edit. Public skills are read only. Do not try to update or delete public skills unless the command output clearly identifies them as owned/editable. Imported .zip or .skill packages are content immutable in MagicPath; they can still be enabled or disabled with skills update <id enable/ disable . Creating or Updating Skills For more than a short one line instruction, write the instructions to a local file and use instructions file . This avoids shell quoting problems and preserves Markdown. A MagicPath skill requires a non empty name, description, and instructions. The description should say when the skill should be used; the instructions should say how to do the work. If a user is turning an observed workflow into a reusable skill, summarize the trigger, constraints, steps, examples, and any files or references the future agent should read. Installing a MagicPath Skill Locally When a user wants a skill from MagicPath installed into their external coding agent, first retrieve it, then recreate it as a local Agent Skills folder: 1. Run npx y magicpath ai skills get <skillIdOrSlug o json . 2. Create a folder named after the skill slug. 3. Write SKILL.md with frontmatter containing at least name and description , followed by the retrieved instructions : 4. If the skill has bundled package files, run npx y magicpath ai skills get <skillIdOrSlug files o json , then fetch each file with file <path and recreate the same relative paths in the local skill folder. 5. Install or register that folder using the current agent host's local skill workflow. If the host supports the Agent Skills CLI, install from the local folder with that tool; otherwise place the folder in the host's documented local skills directory. Ask before writing outside the user's current project or into a global agent configuration directory. Workflow Always use o json for all data returning commands ( search , list projects , list components , list teams , list themes , get theme , skills , selection , active project , info , add , inspect , code ). This gives you structured output to work with instead of human readable tables. Phase 1: Discover 1. Check auth — run npx y magicpath ai whoami o json to verify authentication. 2. Check current selection — if the user references "the selected component," "the selected image," "the design I have selected," or otherwise points at a specific canvas selection , run npx y magicpath ai selection o json . If it returns components, use them directly — skip the search/confirm flow and proceed with the returned generatedName (s). Each returned component also includes selectedRevisionId , the revision currently shown for that component on the canvas. The response can also include selected images ; when you subsequently run code start , those selected images are made available under assets/selected/ as described below. When a downstream command accepts a revision (such as code context revision ), pass this value through so the operation targets the version the user is looking at rather than whichever revision happens to be canonical in the database. 3. Check the active project — if the user references "the project I have open," "this project," "what I'm working on," or otherwise implies a working project context without naming a specific component, run npx y magicpath ai active project o json . It returns the project(s) the user currently has open in their browser, even when nothing is selected. If it returns one project, treat it as the working project and skip the project picker. If it returns multiple, list them and ask which one. If it returns an empty list, the user has no canvas open — reach for list projects and ask the user. Pick the right command for what the user said: selection for a referenced component, active project for a referenced project, list projects + ask if neither. (Note that selection also returns the active projects in its output, so when the user references a component you already get the project for free — no separate active project call needed.) 4. Find components — use npx y magicpath ai search <query o json to search across all projects, or list projects o json then list components <projectId o json to browse. If active project already gave you a project, scope your search to it via list components <projectId o json instead of searching every workspace. 5. See