Matrix Skills

Your computer: install the public pack

The recommended public pack lives at plugins/matrix-os/skills/ and contains three focused skills:

Install all three globally through Matrix's website:

curl -fsSL https://matrix-os.com/install/skills | sh

The Matrix-owned endpoint is a small shell script that delegates to the pinned skills.sh CLI. skills.sh detects supported local agents and installs the pack into their global skill directories. Start a new Codex, Claude Code, OpenCode, or Pi session after installation so it refreshes skill discovery.

Inspect the installer before running it:

curl -fsSL https://matrix-os.com/install/skills

Advanced: manual skills.sh command

The website command is the recommended install path. If you want to call skills.sh directly, the equivalent pinned command is:

pnpm dlx skills@1.5.23 add https://github.com/HamedMP/matrix-os/tree/main/plugins/matrix-os/skills --global --all

To list the pack without installing it, replace --global --all with --list.

Then try:

Use Matrix to check my cloud computer, clone this repository, and run its tests in an observable session.

OpenCode and Pi support shared .agents/skills/ discovery in addition to their own skill directories. Pi only loads project skills after the project is trusted.

Hand off an active task to Matrix

Install the optional matrix-handoff skill when you want Codex or Claude Code to move the current repository and task context into a new project on your Matrix computer:

pnpm dlx skills@1.5.23 add https://github.com/HamedMP/matrix-os/tree/main/.agents/skills/matrix-handoff --global --all

Start a new agent session after installation, then ask it to use $matrix-handoff. Claude Code also exposes /matrix-handoff when you work from a Matrix OS source checkout.

Read the complete matrix-handoff instructions.

The handoff is a two-phase workflow. First, the agent previews the filtered files, optional repository-matched transcript, Matrix destination, selected coding agent, and a SHA-256 approval token. After you approve that exact scope, the agent reruns with the token. The helper stages the inputs again and refuses to upload if the repository files, continuation brief, transcript, agent, profile, or destination basis changed after preview.

By default the destination keeps the repository name: ~/projects/<project-name>. If that directory already exists, handoff stops before uploading and asks you to choose another --project-name; it does not invent a -handoff suffix or overwrite the existing project.

Use --no-history when you want to transfer only the repository and a secret-free continuation brief:

Use $matrix-handoff to move this task to Matrix with Codex, using --no-history.

Matrix computer: build and use apps

The runtime pack lives at skills/matrix/ in the Matrix OS source and is available automatically on your Matrix computer. You do not install this pack with skills.sh. Matrix syncs it into supported agent discovery paths and updates Matrix-managed entries without removing user-managed skills.

The runtime release determines the installed catalog. The pack includes Matrix workflow skills and focused design/motion companions. App builders load matrix-app-builder, matrix-design-system, and matrix-app-ui-patterns first, then add only the motion skills relevant to the task.

Matrix's current brand is the system frame: Teal #0E3422, Coral #D06E53, Gold #F1C379, Green #BED77B, Blue #C5D6E2; Bricolage Grotesque for display, Geist for body/UI, and Geist Mono for code. Generated apps also form a taste brief from your references, domain, desired personality, and density. The goal is a coherent Matrix app that reflects your taste—not the same gradients, glass, capsules, or animation style on every project.

Design and animation companions

The runtime pack also includes emil-design-eng, apple-design, animate, animation-vocabulary, animation-accessibility, animation-performance, css-animations, and review-animations. Agents load relevant instructions and resources when needed rather than copying every skill into every prompt. User-installed skills with the same name remain owner-managed; Matrix does not overwrite them.

Saved Agent recipes keep their admitted skill instructions and, when available, the selected skill's actual file location. Agents resolve linked guides from that skill's directory and read them only as needed with available authorized tools. These guides are current local files and may change; the saved instructions remain the recipe's snapshot. Older recipes without a source location do not guess a path. Selecting skills keeps the current permissions unchanged.

For a new app, ask for a useful primary flow, a clear design direction, and real persistence:

Build a calm project planner. Use the Matrix app-builder and design skills.
Keep a DESIGN.md describing the layout, typography, states, data and motion.
Store projects and tasks in my Postgres through MatrixOS.db.
Open it in Matrix, check save-and-reopen, keyboard navigation and reduced motion,
then refine the rendered app. Tell me which surfaces you actually tested.

When your visual direction is unclear, the builder can invite a style, app link, or inspiration screenshot. You can share your own image or let it choose a direction. Where research and browser tools are available, it can delegate bounded similar-app research, inspect actual screens, and keep the selected references in your project's design/references/. It records the chosen patterns in DESIGN.md and adapts them to your product rather than applying a generic template. Clear briefs do not require a design-approval pause.

Generated products can use a bright minimal, neo-brutal, playful, retro, or neumorphic direction when it fits your brief, mood, and references. The builder chooses the whole visual family—typography, shapes, borders, spacing, imagery, motion, and semantic color roles—and records it in DESIGN.md. “Surprise me” chooses one coherent direction to carry through iterations. Matrix's platform chrome, authentication, and billing retain the Matrix brand.

For apps using shadcn/ui, the builder reads the project's existing components and components.json, where present, and checks current official component guidance before making changes. Fresh presets follow your brief as one coherent visual direction; demonstration presets are examples. Existing custom styles are preserved through reviewed merges. shadcn charts use real app data, responsive containers, clear labels, and accessible summaries or tables.

Windowed apps fill their frame below the titlebar without an extra shell gutter. In Electron Desktop, larger resize targets and a visible corner grip sit just outside native app content; Web Desktop and Web Canvas retain their existing content and resize behavior.

Hosted apps in the updated Electron Desktop bridge can request another installed app with window.MatrixOS.openApp(name, path): void. This is a one-way launch request, not a completion acknowledgement. The target must be an exact installed app root or entry; the catalog supplies its display name. Built-in tools, external URLs and arbitrary files are not accepted by this API.

The builder records the app's visual direction in DESIGN.md, uses Matrix theme tokens, and chooses a layout suited to the job. It checks narrow phone layouts and different app-window widths, keeps primary actions and form fields reachable, and contains necessary wide-table scrolling within the table region. Landing pages use the matrix-landing-design skill from the updated pack; product tools should prioritize their working interface. Motion should support feedback and continuity while keeping repeated actions immediate.

Structured app data belongs in manifest-declared Postgres tables through window.MatrixOS.db. Generated apps use the injected bridge in the sandbox, rather than direct gateway requests, embedded database credentials, or localStorage as a substitute for persistence.

Matrix's kernel, Matrix-launched Claude Code, and Chat Codex receive concise Matrix orientation. Available tools and permission boundaries still depend on the selected route. A skill teaches a workflow; it does not grant a tool or integration action. A successful build is only one check: rendered screenshots, primary-flow testing, persistence, responsive windows, safe failure states, and accessibility establish whether the app is ready to use.

The shared Agent Skills paths make the pack available to Matrix, Claude Code, Codex, OpenCode, Pi, and other compatible runtimes running on the Matrix computer.

For the standalone Agent CLI, remote installs fill missing names while preserving existing entries. The reviewed local refresh update, when included in your release, uses a real local skill source to refresh only Matrix-managed entries through the synchronizer; owner-managed skills and custom aliases remain intact. See the developer installation guide for local and remote setup.

Matrix computer workflow catalog

The catalog below highlights app and motion workflows. Open an entry for its selection boundary and an explicit trigger. Matrix foundation entries link to their public source. Motion entries provide bundled-only motion guidance. Check your runtime’s installed catalog for the exact skills in its release.

Matrix app foundation

Motion direction and discovery

Some focused motion entries below are release-dependent. Use a named skill only when it appears in your installed catalog; the updated pack includes the eight companions listed above.

Motion implementation

Motion quality, accessibility, and review

Matrix OS repository: develop the platform

The Matrix OS source repository carries its development skills under .agents/skills/. These are for Matrix company engineers and contributors working on the platform itself—not for operating a personal Matrix computer or building an ordinary Matrix app.

This repository-scoped set covers workflows such as testing, debugging, code review, pull requests, previews, releases, native UI, authentication, and deployment. Keeping it at the repository root gives supported agents the same engineering playbooks when a contributor checks out Matrix OS.