Agent Matrix Skills

Matrix ships one canonical skill pack under skills/matrix/. Runtime sync projects every skill directory with a SKILL.md into the tool-specific locations for Matrix, Claude Code, Codex, Hermes, and Agent-compatible runtimes.

Skills

Skill	Purpose
`matrix-app-builder`	Build Matrix apps as Vite React TypeScript projects with `matrix.json` and verified `dist/` output.
`matrix-app-ui-patterns`	Build stable app interiors for windowed, mobile, dashboard, data, and canvas contexts.
`matrix-design-system`	Apply Matrix theme, shadcn-style component patterns, icon quality rules, and iframe-safe app layouts.
`matrix-integrations`	Use platform-owned integrations without copying provider secrets into agents or customer VPSes.
`matrix-dev-vps`	Develop Matrix from inside a user/dev VPS with hot reload, previews, and auth-aware tunnels.
`matrix-debug-app`	Fix `needs_build`, manifest problems, bundle/icon 404s, console errors, and integration proxy issues.
`matrix-landing-design`	Build public Matrix OS marketing and landing surfaces without mixing those patterns into apps.

Sync targets

MATRIX_SKILL_TARGETS=matrix,claude,codex,hermes ./scripts/sync-matrix-agent-skills.sh skills/matrix

Consumer	Runtime path
Matrix kernel	`$MATRIX_HOME/.agents/skills/<skill>/SKILL.md`
Codex	`$HOME/.agents/skills/<skill>/SKILL.md`
Claude Code	`$HOME/.claude/skills/<skill>/SKILL.md`
Hermes	`$HERMES_HOME/skills/<skill>/SKILL.md`

Matrix OS marketplace plugin

Local Codex users can install one complete Matrix OS marketplace product from a Matrix OS repository checkout:

codex plugin marketplace add "$(pwd)"

The marketplace name and plugin ID are Matrix OS (matrix-os), its category is Productivity, and its description is “Run development work on your Matrix cloud computer.” If you installed an unpublished preview under the old matrix-onboarding namespace, remove it and install the renamed plugin once:

codex plugin remove matrix-onboarding@matrix-os
codex plugin add matrix-os@matrix-os

The product bundles three skills:

Skill	Purpose
`matrix-onboarding`	Set up, authenticate, diagnose, and recover a Matrix computer.
`matrix-cloud-run`	Run bounded commands and sandboxed coding-agent tasks on Matrix.
`matrix-github-project`	Clone, verify, reuse, change, and validate GitHub projects on Matrix.

Try a starter prompt:

Build a new app on my Matrix computer.
Clone this GitHub repo on Matrix and make a change.
Run this command on my Matrix computer.

Authentication stays on Matrix

Matrix, Codex, Claude, and GitHub use their own browser or device login flows. The plugin does not scan, read, or upload local credential files. If an agent or GitHub CLI is missing, it asks before installing a global tool and prefers Matrix's visible developer-tool installation path.

Run commands and coding work

The plugin checks the hosted cloud profile, matrix doctor, identity, status, instance readiness, and the selected agent's remote version and authentication status. If matrix instance info --json reports ready: true with source: execution_probe, command execution is healthy even though the management plane is degraded; the workflow continues and reports the degraded metadata path. It stops only when both checks fail.

Every remote command runs in a unique session created by the Matrix CLI. The workflows never create or use tabs. Each additional command, terminal, or concurrent task gets a separate session whose name and matrix shell connect command are reported immediately.

The plugin normalizes a safe relative destination under the Matrix home and inspects existing contents before running work.

For a new app, it creates apps/<slug> before selecting it. -C only selects an existing directory; it never creates one.

matrix run -it --session create-app-<slug>-<suffix> -- mkdir -p -- apps/<slug>
matrix run -it --session task-<slug>-<suffix> -C apps/<slug> -- <argv...>
matrix shell connect task-<slug>-<suffix>

Coding tasks use the same unique named-session policy:

matrix run -it --session task-<slug>-<suffix> -C <dir> -- codex --ask-for-approval never --sandbox workspace-write exec -- <prompt>
matrix shell connect task-<slug>-<suffix>

Codex uses read-only for inspection and narrow workspace-write for changes. The plugin never uses danger-full-access without explicit direction. Claude Code uses claude --permission-mode auto -p <prompt> in its own named session so it can proceed without repetitive permission questions while retaining Claude's safety classifier. If auto mode is unavailable, the workflow stops and reports the limitation instead of using a permission bypass.

Work on a GitHub project

GitHub authentication runs on the Matrix computer with remote gh auth status and a unique auth-github-<suffix> browser-login session. Ordinary repositories live under projects/<repo>; only checkouts meant to run directly as Matrix apps use apps/<slug>.

matrix run -it --session clone-<repo>-<suffix> -- gh repo clone <owner>/<repo> projects/<repo>
matrix run -it --session inspect-status-<repo>-<suffix> -C projects/<repo> -- git status --porcelain=v1 --branch
matrix run -it --session inspect-origin-<repo>-<suffix> -C projects/<repo> -- git remote get-url origin

An existing checkout is reused only when its normalized GitHub owner/repository matches the request. The workflow stops on non-Git collisions, mismatched origins, and dirty or mid-operation worktrees. It never resets, cleans, stashes, or overwrites user changes automatically. It reads repository instructions, README files, lockfiles, and environment examples before setup or validation, and pushes or opens a PR only when explicitly requested.

Agent bootstrap

matrix login
matrix run -it --session auth-claude-a1b2 -- claude
matrix run -it --session auth-codex-c3d4 -- codex login
matrix run -it --session auth-github-e5f6 -- gh auth login --hostname github.com --web
matrix shell connect auth-github-e5f6

Use a separate uniquely named session for each setup workflow so the user, Matrix web terminal, Claude, Codex, or Hermes can observe and reattach each VPS task. Never use tabs to multiplex work.

Security boundary

Skills contain instructions only. They should not carry secrets, and they should prefer Matrix gateway/platform APIs for authenticated actions.