Matrix Skills

Understand and install the three Matrix skill sets for local agents, Matrix computers, and Matrix OS contributors.

Matrix uses Agent Skills to give coding agents the right instructions for where they are running. The local computer, a Matrix computer, and the Matrix OS source repository have different jobs, so they use separate skill sets.

Three skill sets

1. Local computer

Install skills/matrix-os/ on your laptop or workstation. It teaches an agent to install the Matrix CLI, sign in, diagnose the connection, and run work on your Matrix computer.

2. Matrix computer

The skills/matrix/ pack is available automatically on your Matrix computer. It teaches agents to build, open, design, integrate, and debug Matrix apps.

3. Matrix OS development

The .agents/skills/ set lives in the Matrix OS repository for company engineers and contributors developing Matrix OS itself.

Local computer: operate Matrix

The public matrix-os skill lives at skills/matrix-os/. Install it in a local project when you want Claude Code, Codex, OpenCode, or Pi to operate your Matrix computer through the CLI. It covers CLI installation, cloud login, readiness checks, named terminal sessions, remote agent authentication, and recovery.

Run the matching command from your project root on your local computer:

Claude Code

npx skills add HamedMP/matrix-os --skill matrix-os --agent claude-code

Codex

npx skills add HamedMP/matrix-os --skill matrix-os --agent codex

OpenCode

npx skills add HamedMP/matrix-os --skill matrix-os --agent opencode

Pi

npx skills add HamedMP/matrix-os --skill matrix-os --agent pi

To install it for all four Matrix-supported coding agents:

npx skills add HamedMP/matrix-os --skill matrix-os --agent claude-code --agent codex --agent opencode --agent pi

The skills.sh CLI installs project-local skills by default. Start a new agent session after installation, then try:

Set up Matrix OS as my cloud computer and start my coding agent there.

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.

Review skills before installing

Skills can influence agent behavior and may include executable helpers. Review the source and the skills.sh security information before installing any third-party skill.

Hand off an active task to Matrix

Install the 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:

npx skills add HamedMP/matrix-os --skill matrix-handoff --agent codex --agent claude-code

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.

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.

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.

Authentication stays separate

The handoff excludes common credential files, private keys, .env files, agent auth databases, dependencies, and build output. It never copies local authentication into Matrix. Authenticate GitHub and the selected coding agent through their own browser or device flow, or use a Matrix-managed SSH key created inside the runtime.

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 need to install this pack with npx skills. Matrix syncs it into supported agent discovery paths and updates it with matrix sync.

matrix-app-builder

Build and open Matrix apps as Vite React TypeScript projects with matrix.json manifests, Postgres-backed data, and verified production output.

matrix-app-ui-patterns

Choose stable layouts for windowed, mobile, dashboard, data, and canvas app contexts.

matrix-design-system

Apply Matrix colors, typography, icons, motion, and component patterns.

matrix-integrations

Use Matrix-owned integrations without exposing provider credentials to apps or agents.

matrix-debug-app

Fix build, manifest, bundle, icon, console, and integration-proxy failures.

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.

Skills are instructions, not credentials

Matrix skills do not contain provider credentials. Authenticated actions go through Matrix APIs and each provider's supported login flow.

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.

Skills and AGENTS.md have different jobs

Agent Skills are reusable, on-demand workflows. AGENTS.md provides repository-level setup, testing, style, security, and contribution rules that coding agents read automatically. Matrix OS uses both: AGENTS.md defines the boundaries, while development skills guide specific workflows.

Choose the right set

Where the agent runs	What you want it to do	Skill source
Your local computer	Connect to and operate your Matrix computer	`skills/matrix-os/`
Your Matrix computer	Build, open, integrate, and debug apps	`skills/matrix/`
Matrix OS source checkout	Develop and contribute to Matrix OS	`.agents/skills/`