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

Publishing and Installing Skills

Skills are shareable through the App Store:

IPC Tool	Description
`publish_skill`	Validates and pushes a local skill to the platform registry
`install_skill`	Downloads a skill from the registry to `~/.agents/skills/<skill>/SKILL.md`

See the App Store docs for store UI and browsing.

Skills System

On this page