Skills System

Skill validation, runtime synchronization, the 19-skill Matrix app-building pack, and public skills.sh distribution.

The skills system enables demand-loaded capabilities for the AI kernel. Matrix-shipped coding skills use the Agent Skills directory format: SKILL.md plus optional supporting files. The canonical Matrix pack lives in skills/matrix/ and is synced into runtime discovery paths for Matrix, Claude Code, Codex, and Hermes.

Skill Format

~/.agents/skills/matrix-app-builder/SKILL.md

---
name: matrix-app-builder
description: Build Matrix OS apps as Vite React TypeScript projects with matrix.json manifests, Matrix theme integration, Postgres-backed app data, and production build verification.
license: MIT
metadata:
  version: 1.0.0
  author: Matrix OS
  platforms: [linux, macos]
  agent:
    tags: [Matrix OS, apps, Vite, React, TypeScript]
    related_skills: [matrix-design-system, matrix-integrations, matrix-debug-app]
---

Default to Vite, React 19, TypeScript, `runtime: "vite"`, and Matrix/Postgres bridge APIs.
...

Frontmatter Schema

Skills are validated at boot time with a Zod schema in packages/kernel/src/skills.ts:

Field	Type	Required	Description
`name`	string	Yes	Unique skill identifier
`description`	string	Yes	Short description (shown in skills TOC)
`license`	string	No	Skill license
`metadata`	object	No	Agent Skills-compatible metadata such as version, author, platforms, tags, and related skills
`triggers`, `examples`, `composable_with`	string[]	No	Matrix legacy extensions still accepted

Validation Behavior

Missing name or description: error logged, skill skipped
Unknown fields: ignored (forward-compatible)
Malformed YAML: skill file skipped with a warning
All validation happens in loadSkills() at kernel boot

Skill Loading Flow

Sync: scripts/sync-matrix-agent-skills.sh projects skills/matrix/ into runtime skill folders.
Boot: loadSkills() reads ~/.agents/skills/*/SKILL.md, ~/.claude/skills/*/SKILL.md, and legacy flat files if present.
TOC injection: buildSkillsToc() creates a concise table of contents injected into the system prompt.
On-demand load: the load_skill IPC tool fetches the full skill body into the agent's context.
Composable loading: if the loaded skill has composable_with, companion skills are auto-loaded too.

Circular loading prevention

The skill loader tracks which skills have already been loaded in the current session. Circular composable_with references are detected and skipped.

Skill Caching

To avoid redundant disk reads:

Memory cache: an in-memory Map<string, string> stores skill bodies after first read
Cache invalidation: the file watcher clears a cache entry when a skill file changes on disk

Knowledge files (e.g., app-generation.md) are also cached at kernel boot via getKnowledge(name).

Matrix App-Building Pack

Matrix OS ships 19 internal skills in three functional groups:

Group	Skills	Covers
Matrix app foundation	`matrix-app-builder`, `matrix-app-ui-patterns`, `matrix-design-system`, `matrix-integrations`, `matrix-dev-vps`, `matrix-debug-app`	Vite React apps, manifests, Postgres bridge access, integrations, current Matrix brand, user-taste adaptation, localhost previews, builds, and debugging
Motion decisions and implementation	`animate`, `css-animations`, `motion-react`, `gesture-ui`, `scroll-animations`, `animation-vocabulary`	Purpose, vocabulary, CSS/WAAPI, Motion React, gestures, layout/shared-element transitions, and scroll motion
Motion quality	`animation-accessibility`, `animation-performance`, `debug-animation`, `find-animation-opportunities`, `improve-animations`, `review-animations`, `pick-ui-library`	Reduced motion, performance, debugging, opportunity discovery, audits, review standards, and library choice

skills/matrix/ is the source of truth. scripts/sync-matrix-agent-skills.sh projects it into supported runtime paths and records Matrix-owned entries in .matrix-os-managed-skills. A later sync can replace or retire those managed entries without deleting a user's own skills.

The builder loads the foundation skills explicitly before app work. It treats Matrix's palette and typography as the shell/system frame, creates a short taste brief from the user's references and app domain, and loads only the motion skills the interface actually needs.

Public skills.sh Pack

The user-installable pack is intentionally smaller than the Matrix-computer pack. plugins/matrix-os/skills/ exposes matrix-onboarding, matrix-cloud-run, and matrix-github-project; it does not copy internal app-generation policy onto the user's local computer.

The repository pins skills.sh 1.5.23 in scripts/install-public-matrix-skills.sh:

./scripts/install-public-matrix-skills.sh

That script installs the GitHub subdirectory globally with --all. Keep the CLI version exact and review a newer release against the repository's dependency-age policy before updating it.

Build Pipeline

Generated user-facing apps default to Vite + React. Plain HTML apps are only for explicit throwaway requests.

Offline-First Builds

pnpm store path configured in ~/system/.pnpm-store
pnpm install --prefer-offline skips registry checks when packages are cached
Common dependencies (react, react-dom, vite, typescript) pre-populated in the store

Template Projects

Pre-built scaffolds in ~/templates/react-app/ are copied and modified (only App.tsx + App.css change). Skips pnpm install when node_modules already exist.

Build Error Recovery

On build failure:

Parse the error
Attempt a single fix
Rebuild (max 2 retries)
If still failing: report the blocker with the exact failing command and keep the Vite project intact

Use Matrix Skills for the current bundled packs, supported agents, and public skills.sh installation instructions.

The planned Matrix App Gallery focuses first on curated Matrix apps. A public skills registry, publishing workflow, and one-click gallery installation are not available as an end-to-end production gallery experience. Agent tools or legacy registry endpoints should not be presented as proof that these flows are available to users.

Skills System

On this page