Skills and Extensions: Extending Space Agent with SKILL.md

Skills are the primary mechanism for giving the Space Agent on-demand capabilities. A skill is a plain Markdown file (SKILL.md) that the agent can load into its prompt context at runtime. Each skill file lives inside a module’s ext/skills/ folder, carries YAML frontmatter that controls when and how it appears, and can reference small browser-side JavaScript helpers via stable /mod/... imports. Skills keep the base prompt lean while making deep, task-specific guidance available exactly when it is needed.

Skill Discovery

The agent discovers top-level skills automatically from the readable module tree using one glob pattern:

mod/*/*/ext/skills/*/SKILL.md

A few important rules govern discovery:

Top-level skills (matching the pattern above) appear in the prompt catalog automatically.
Nested skills (e.g., ext/skills/development/modules-routing/SKILL.md) are not listed by default and can only be loaded through explicit routing skills or a direct space.skills.load(...) call.
Skill IDs are relative to ext/skills/ without the trailing /SKILL.md. For example, ext/skills/browser-control/SKILL.md has the ID browser-control.
Same-module layered overrides replace lower-ranked skill files before the catalog is built.
Conflicting IDs across modules are omitted from the catalog, and loading a conflicting ID fails with an ambiguity error.

Loading a Skill

On-demand loading uses a single call:

await space.skills.load("skill/path");

The call returns the typed skill object. What happens next depends on the skill’s placement:

Placement	Behavior
`history`	Writes the skill body into conversation history; treated as a read stage — the next turn should act on it
`system`	Registers the skill body in the system prompt; returns `skill loaded to system message`
`transient`	Registers the skill body in transient context; returns `skill loaded to transient area`

Auto-loaded skills may only land in system or transient. A missing, invalid, or explicit history placement for an auto-loaded skill falls back to system unless the skill explicitly sets transient.

Skill Frontmatter Metadata

Each SKILL.md file may include a YAML frontmatter block at the top:

---
metadata:
  when: true                          # or { tags: ["onscreen", "space:open"] }
  loaded: true                        # or { tags: ["onscreen"] } for auto-load
  placement: system                   # system | transient | history
---

Field	Purpose
`when`	`true` or `{ tags: [...] }` — requires all listed tags before the skill becomes catalog-loadable
`loaded`	`true` or `{ tags: [...] }` — triggers automatic prompt injection when the condition passes
`placement`	Where the skill body lands: `system`, `transient`, or `history`

Both when and loaded are evaluated against the current document’s live <x-context> tag union at catalog-build time and at every explicit skill load.

Context Tags and Skill Visibility

Context tags are emitted by <x-context> elements in mounted DOM. The framework unions all data-tags values in the current document each time the skill catalog is built. Skills use these tags to become visible only in the right context:

Tag	Emitted by
`onscreen`	`_core/onscreen_agent/panel.html` — overlay is mounted
`admin`	`_core/admin/views/shell/shell.html` — admin shell is active
`space:open`	`_core/spaces/view.html` — a Space is currently open
`space:id:<id>`	`_core/spaces/view.html` — identifies the open Space
`browser:open`	`_core/web_browsing/window.html` — at least one browser surface is open
`runtime-browser`	Framework bootstrap — running in a normal web session
`runtime-app`	Framework bootstrap — running in the packaged desktop app
`route:<path>`	`_core/router/view.html` — the current hash route path

First-Party Shared Skills

Space Agent ships a set of first-party top-level skills in _core/skillset/:

development

Frontend development router. Always included; not tag-gated. Stays concise but keeps one visible subsection per nested development skill for fast follow-up routing.

browser-manager

Browser window management for the overlay. Auto-loads on onscreen surfaces. Covers opening and closing stand-alone browser windows via the numeric-id space.browser helpers.

browser-control

In-browser page automation. Auto-loads when browser:open is present. Teaches space.browser navigation, DOM inspection, typed ref boxes, and ref-targeted actions.

memory

Prompt-include-backed user memory. Auto-loaded into system prompts. Standardizes ~/memory/behavior.system.include.md and ~/memory/memories.transient.include.md.

file-download

File download guidance for the overlay. Requires the onscreen tag.

pdf-report

Generic HTML/CSS-to-PDF pipeline. Imports /mod/_core/skillset/ext/skills/pdf-report/pdf-report.js for the structured report builder and download wrappers.

spaces

Space selection and space.yaml editing. Auto-loaded unconditionally. Covers opening, creating, removing, and editing spaces.

space-widgets

Widget authoring inside an open Space. Auto-loads only when space:open is present. Teaches the staged readWidget → patchWidget → renderWidget flow.

screenshots

Page screenshot helper. Lazy-loads the vendored html2canvas@1.4.1 bundle from /mod/_core/skillset/vendor/html2canvas.min.js — no CDN required.

user-management

User management guidance for the overlay. Requires the onscreen tag.

documentation

Carries the compact docs map directly in its body. Load this first for broad orientation, then use the documentation helper for focused reads.

Documentation Skill and Helper

The documentation skill provides a compact map of all available docs. Load it first for orientation:

await space.skills.load("documentation");

For focused follow-up reads once you know the path you need, use the documentation helper directly:

await space.skills.load("documentation");
const doc = await import("/mod/_core/documentation/documentation.js");

// Read a specific doc by relative path
const filesDoc = await doc.read("server/api/files.md");

// Get the full URL for a doc
const url = doc.url("server/api/files.md");

Use the documentation skill for fast orientation, the helper for focused doc reads once you know the relative path, the relevant AGENTS.md file for the concrete module contract, and code for exact implementation detail.

HTML Extension Anchors

Modules declare composable seams using <x-extension>:

<x-extension id="some/path"></x-extension>

Resolution rules:

The caller names only the seam ID.
Matching files live at mod/<author>/<repo>/ext/html/some/path/*.html.
Extension files should stay thin — they normally mount the real component from the module root.
Uncached HTML <x-extension> lookups are batched before they hit /api/extensions_load. By default, the frontend flushes the queue on the next animation frame.

Important first-party router seams:

Seam ID	Used by
`_core/router/shell_start`	`_core/onscreen_menu` mounts the viewport-fixed header bar
`_core/router/shell_end`	Available for shell-level end extensions
`page/router/route/start`	Route content start
`page/router/route/end`	Route content end
`page/router/overlay/start`	Overlay layer start
`page/router/overlay/end`	`_core/web_browsing` mounts floating browser windows here

JavaScript Extension Hooks

Behavior seams use space.extend:

space.extend(import.meta, async function myFeatureName() {
  // hook body
});

Hook files live at mod/<author>/<repo>/ext/js/<extension-point>/*.js or *.mjs. Each wrapped function automatically exposes /start and /end hook points. JS hook lookups do not use the animation-frame batch window — the runtime requests them immediately because callers await them directly. Key framework hook points:

Hook point	Purpose
`_core/framework/head/end`	HTML seam in `document.head` for declarative head-side tags or inline bootstraps
`_core/framework/initializer.js/initialize/end`	Imperative setup after framework bootstrap
`_core/onscreen_agent/llm.js/buildOnscreenAgentSystemPromptSections`	Inject system prompt sections
`_core/onscreen_agent/llm.js/buildOnscreenAgentTransientSections`	Inject transient context sections

The `x-inject` Directive

The x-inject directive is a delayed-target injection helper that mirrors Alpine’s x-teleport for <template> roots:

<!-- Source template in a route-owned component -->
<template x-inject="[id='_core/onscreen_menu/bar_start']">
  <button>My Route Button</button>
</template>

x-inject waits for the selector when the target seam is not yet mounted, and tears down that wait when the source template unmounts. This lets route-owned controls appear in shared shell chrome without becoming permanent shell extensions.

_core/spaces, _core/dashboard, and _core/time_travel all use x-inject to place route-owned controls into the shared [id="_core/onscreen_menu/bar_start"] container, keeping those controls route-scoped so they disappear when the route unmounts.

Get Started

Core Concepts

CLI Reference

App Runtime

Self-Hosting

Skills and Extensions: Extending Space Agent with SKILL.md

Skill Discovery

Loading a Skill

Skill Frontmatter Metadata

Context Tags and Skill Visibility

First-Party Shared Skills

development

browser-manager

browser-control

memory

file-download

pdf-report

spaces

space-widgets

screenshots

user-management

documentation

Documentation Skill and Helper

HTML Extension Anchors

JavaScript Extension Hooks

The `x-inject` Directive

Build docs developers (and LLMs) love

Get Started

Core Concepts

CLI Reference

App Runtime

Self-Hosting

Documentation Index

​Skill Discovery

​Loading a Skill

​Skill Frontmatter Metadata

​Context Tags and Skill Visibility

​First-Party Shared Skills

development

browser-manager

browser-control

memory

file-download

pdf-report

spaces

space-widgets

screenshots

user-management

documentation

​Documentation Skill and Helper

​HTML Extension Anchors

​JavaScript Extension Hooks

​The x-inject Directive

Build docs developers (and LLMs) love

Skill Discovery

Loading a Skill

Skill Frontmatter Metadata

Context Tags and Skill Visibility

First-Party Shared Skills

Documentation Skill and Helper

HTML Extension Anchors

JavaScript Extension Hooks

The `x-inject` Directive