Skills System

Skill validation, caching, composable skills, domain-specific app skills, and build pipeline optimization.

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.
version: 1.0.0
author: Matrix OS
license: MIT
platforms: [linux, macos]
metadata:
  hermes:
    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)
`version`	string	No	Skill version
`author`	string	No	Skill author
`license`	string	No	Skill license
`platforms`	string[]	No	Supported OS platforms
`metadata.hermes`	object	No	Hermes tags, related skills, config, and tool requirements
`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).

Domain-Specific App Skills

Matrix OS ships a small canonical coding pack:

Skill	Covers
`matrix-app-builder`	Vite React TypeScript apps, `matrix.json`, `dist/`, Postgres bridge access
`matrix-design-system`	Matrix theme variables, shadcn-style controls, iframe-safe layouts, icon rules
`matrix-integrations`	Platform-owned OAuth/integration calls without storing provider secrets on VPSes
`matrix-dev-vps`	Dev workflow from a Matrix user/dev VPS
`matrix-debug-app`	`needs_build`, manifest, icon, bundle, console, and integration proxy debugging

skills/matrix/ is the source of truth. Runtime paths are symlinks or generated mirrors.

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