Skills

Skills

Skills are markdown instruction files that teach the agent how and when to use tools. Each skill lives in a directory containing a SKILL.md file with YAML frontmatter and a markdown body. OmeniaClaw loads bundled skills plus any local overrides, and filters them at load time based on environment, config, and binary presence.

Creating skills

Build and test a custom skill from scratch.

Skill Workshop

Review and approve agent-drafted skill proposals.

Skills config

Full skills.* config schema and agent allowlists.

ClawHub

Browse and install community skills.

Loading order

OmeniaClaw loads from these sources, highest precedence first. When the same skill name appears in multiple places, the highest source wins.

Priority	Source	Path
1 — highest	Workspace skills	`<workspace>/skills`
2	Project agent skills	`<workspace>/.agents/skills`
3	Personal agent skills	`~/.agents/skills`
4	Managed / local skills	`~/.OmeniaClaw/skills`
5	Bundled skills	shipped with the install
6 — lowest	Extra directories	`skills.load.extraDirs` + plugin skills

Skill roots support grouped layouts. OmeniaClaw discovers a skill whenever SKILL.md appears anywhere under a configured root:

text

<workspace>/skills/research/SKILL.md          ✓ found as "research"<workspace>/skills/personal/research/SKILL.md ✓ also found as "research"

The folder path is for organization only. The skill's name, slash command, and allowlist key all come from the name frontmatter field (or the directory name when name is missing).

Per-agent vs shared skills

In multi-agent setups, each agent has its own workspace. Use the path that matches your desired visibility:

Scope	Path	Visible to
Per-agent	`<workspace>/skills`	Only that agent
Project-agent	`<workspace>/.agents/skills`	Only that workspace's agent
Personal-agent	`~/.agents/skills`	All agents on this machine
Shared managed	`~/.OmeniaClaw/skills`	All agents on this machine
Extra dirs	`skills.load.extraDirs`	All agents on this machine

Agent allowlists

Skill location (precedence) and skill visibility (which agent can use it) are separate controls. Use allowlists to restrict which skills an agent sees, regardless of where they are loaded from.

json5

{  agents: {    defaults: {      skills: ["github", "weather"], // shared baseline    },    list: [      { id: "writer" }, // inherits github, weather      { id: "docs", skills: ["docs-search"] }, // replaces defaults entirely      { id: "locked-down", skills: [] }, // no skills    ],  },}

Allowlist rules

Omit agents.defaults.skills to leave all skills unrestricted by default.
Omit agents.list[].skills to inherit agents.defaults.skills.
Set agents.list[].skills: [] to expose no skills for that agent.
A non-empty agents.list[].skills list is the final set — it does not merge with defaults.
The effective allowlist applies across prompt building, slash-command discovery, sandbox sync, and skill snapshots.

Plugins and skills

Plugins can ship their own skills by listing skills directories in OmeniaClaw.plugin.json (paths relative to the plugin root). Plugin skills load when the plugin is enabled — for example, the browser plugin ships a browser-automation skill for multi-step browser control.

Plugin skill directories merge at the same low-precedence level as skills.load.extraDirs, so a same-named bundled, managed, agent, or workspace skill overrides them. Gate them via metadata.OmeniaClaw.requires.config on the plugin's config entry.

See Plugins and Tools for the full plugin system.

Skill Workshop

Skill Workshop is a proposal queue between the agent and your active skill files. When the agent spots reusable work, it drafts a proposal instead of writing directly to SKILL.md. You review and approve before anything changes.

bash

OmeniaClaw skills workshop listOmeniaClaw skills workshop inspect <proposal-id>OmeniaClaw skills workshop apply <proposal-id>

See Skill Workshop for the full lifecycle, CLI reference, and configuration.

Installing from ClawHub

ClawHub is the public skills registry. Use OmeniaClaw skills commands for install and update, or the clawhub CLI for publish and sync.

Action	Command
Install a skill into the workspace	`OmeniaClaw skills install <slug>`
Install from a Git repository	`OmeniaClaw skills install git:owner/repo@ref`
Install a local skill directory	`OmeniaClaw skills install ./path/to/skill --as my-tool`
Install for all local agents	`OmeniaClaw skills install <slug> --global`
Update all workspace skills	`OmeniaClaw skills update --all`
Update a shared managed skill	`OmeniaClaw skills update <slug> --global`
Update all shared managed skills	`OmeniaClaw skills update --all --global`
Verify a skill's trust envelope	`OmeniaClaw skills verify <slug>`
Print the generated Skill Card	`OmeniaClaw skills verify <slug> --card`
Publish / sync via ClawHub CLI	`clawhub sync --all`

Install details

OmeniaClaw skills install installs into the active workspace skills/ directory by default. Add --global to install into the shared ~/.OmeniaClaw/skills directory, visible to all local agents unless agent allowlists narrow it.

Git and local installs expect SKILL.md at the source root. The slug comes from SKILL.md frontmatter name when valid, then falls back to the directory or repository name. Use --as <slug> to override. OmeniaClaw skills update tracks ClawHub installs only — reinstall Git or local sources to refresh them.

Verification and security scanning

OmeniaClaw skills verify <slug> asks ClawHub for the skill's clawhub.skill.verify.v1 trust envelope. Installed ClawHub skills verify against the version and registry recorded in .clawhub/origin.json.

ClawHub skill pages expose the latest security scan state before install, with detail pages for VirusTotal, ClawScan, and static analysis. The command exits non-zero when ClawHub marks verification as failed. Publishers recover false positives through the ClawHub dashboard or clawhub skill rescan <slug>.

Private archive installs

Gateway clients that need non-ClawHub delivery can stage a zip skill archive with skills.upload.begin, skills.upload.chunk, and skills.upload.commit, then install with skills.install({ source: "upload", ... }). This path is off by default and requires skills.install.allowUploadedArchives: true in OmeniaClaw.json. Normal ClawHub installs never need that setting.

Security

Path containment

Workspace, project-agent, and extra-dir skill discovery only accepts skill roots whose resolved realpath stays inside the configured root, unless skills.load.allowSymlinkTargets explicitly trusts a target root. Skill Workshop writes through those trusted targets only when skills.workshop.allowSymlinkTargetWrites is enabled. Managed ~/.OmeniaClaw/skills and personal ~/.agents/skills may contain symlinked skill folders, but every SKILL.md realpath must still stay inside its resolved skill directory.

Operator install policy

Configure security.installPolicy to run a trusted local policy command before skill installs continue. The policy receives metadata and the staged source path, applies to ClawHub, uploaded, Git, local, update, and dependency-installer paths, and fails closed when the command cannot return a valid decision.

Secret injection scope

skills.entries.*.env and skills.entries.*.apiKey inject secrets into the host process for that agent turn only — not into the sandbox. Keep secrets out of prompts and logs.

For the broader threat model and security checklists, see Security.

SKILL.md format

Every skill needs at minimum a name and description in the frontmatter:

markdown

---name: image-labdescription: Generate or edit images via a provider-backed image workflow--- When the user asks to generate an image, use the `image_generate` tool...

Optional frontmatter keys

homepagestring

URL shown as "Website" in the macOS Skills UI. Also supported via metadata.OmeniaClaw.homepage.

user-invocablebooleandefault: true

When true, the skill is exposed as a user-invocable slash command.

disable-model-invocationbooleandefault: false

When true, OmeniaClaw keeps the skill's instructions out of the agent's normal prompt. The skill is still available as a slash command when user-invocable is also true.

command-dispatch"tool"

When set to tool, the slash command bypasses the model and dispatches directly to a registered tool.

command-toolstring

Tool name to invoke when command-dispatch: tool is set.

command-arg-mode"raw"default: raw

For tool dispatch, forwards the raw args string to the tool with no core parsing. The tool receives { command: "<raw args>", commandName: "<slash command>", skillName: "<skill name>" }.

Gating

OmeniaClaw filters skills at load time using metadata.OmeniaClaw (single-line JSON in the frontmatter). A skill with no metadata.OmeniaClaw block is always eligible unless explicitly disabled.

markdown

---name: image-labdescription: Generate or edit images via a provider-backed image workflowmetadata:  {    "OmeniaClaw":      {        "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"] },        "primaryEnv": "GEMINI_API_KEY",      },  }---

alwaysboolean

When true, always include the skill and skip all other gates.

emojistring

Optional emoji shown in the macOS Skills UI.

homepagestring

Optional URL shown as "Website" in the macOS Skills UI.

os"darwin" | "linux" | "win32"

Platform filter. When set, the skill is only eligible on the listed OSes.

requires.binsstring[]

Each binary must exist on PATH.

requires.anyBinsstring[]

At least one binary must exist on PATH.

requires.envstring[]

Each env var must exist in the process or be provided via config.

requires.configstring[]

Each OmeniaClaw.json path must be truthy.

primaryEnvstring

Env var name associated with skills.entries.<name>.apiKey.

installobject[]

Optional installer specs used by the macOS Skills UI (brew / node / go / uv / download).

Installer specs

Installer specs tell the macOS Skills UI how to install a dependency:

markdown

---name: geminidescription: Use Gemini CLI for coding assistance and Google search lookups.metadata:  {    "OmeniaClaw":      {        "emoji": "♊️",        "requires": { "bins": ["gemini"] },        "install":          [            {              "id": "brew",              "kind": "brew",              "formula": "gemini-cli",              "bins": ["gemini"],              "label": "Install Gemini CLI (brew)",            },          ],      },  }---

Installer selection rules

When multiple installers are listed, the gateway picks one preferred option (brew when available, otherwise node).
If all installers are download, OmeniaClaw lists each entry so you can see all available artifacts.
Specs can include os: ["darwin"|"linux"|"win32"] to filter by platform.
Node installs honor skills.install.nodeManager in OmeniaClaw.json (default: npm; options: npm / pnpm / yarn / bun). This only affects skill installs; the Gateway runtime should still be Node.
Gateway installer preference: Homebrew → uv → configured node manager → go → download.

Per-installer details

Homebrew: OmeniaClaw does not auto-install Homebrew or translate brew formulas into system package commands. In Linux containers without brew, brew-only installers are hidden; use a custom image or install the dependency manually.
Go: if go is missing and brew is available, the gateway installs Go via Homebrew first and sets GOBIN to Homebrew's bin.
Download: url (required), archive (tar.gz | tar.bz2 | zip), extract (default: auto when archive detected), stripComponents, targetDir (default: ~/.OmeniaClaw/tools/<skillKey>).

Sandboxing notes

requires.bins is checked on the host at skill load time. If an agent runs in a sandbox, the binary must also exist inside the container. Install it via agents.defaults.sandbox.docker.setupCommand or a custom image. setupCommand runs once after container creation and requires network egress, a writable root FS, and a root user in the sandbox.

Config overrides

Toggle and configure bundled or managed skills under skills.entries in ~/.OmeniaClaw/OmeniaClaw.json:

json5

{  skills: {    entries: {      "image-lab": {        enabled: true,        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },        config: {          endpoint: "https://example.invalid",          model: "nano-pro",        },      },      peekaboo: { enabled: true },      sag: { enabled: false },    },  },}

enabledboolean

false disables the skill even when bundled or installed. The coding-agent bundled skill is opt-in — set skills.entries.coding-agent.enabled: true and ensure one of claude, codex, opencode, or another supported CLI is installed and authenticated.

apiKeystring | { source, provider, id }

Convenience field for skills that declare metadata.OmeniaClaw.primaryEnv. Supports a plaintext string or a SecretRef object.

env"Record<string,

configobject

Optional bag for custom per-skill configuration fields.

allowBundledstring[]

Optional allowlist for bundled skills only. When set, only bundled skills in the list are eligible. Managed and workspace skills are unaffected.

Environment injection

When an agent run starts, OmeniaClaw:

Reads skill metadata

OmeniaClaw resolves the effective skill list for the agent, applying gating rules, allowlists, and config overrides.

Injects env and API keys

skills.entries.<key>.env and skills.entries.<key>.apiKey are applied to process.env for the duration of the run.

Builds the system prompt

Eligible skills are compiled into a compact XML block and injected into the system prompt.

Restores the environment

After the run ends, the original environment is restored.

For the bundled claude-cli backend, OmeniaClaw also materializes the same eligible skill snapshot as a temporary Claude Code plugin and passes it via --plugin-dir. Other CLI backends use the prompt catalog only.

Snapshots and refresh

OmeniaClaw snapshots eligible skills when a session starts and reuses that list for all subsequent turns in the session. Changes to skills or config take effect on the next new session.

Skills refresh mid-session in two cases:

The skills watcher detects a SKILL.md change.
A new eligible remote node connects.

The refreshed list is picked up on the next agent turn. If the effective agent allowlist changes, OmeniaClaw refreshes the snapshot to keep visible skills aligned.

Skills watcher

By default, OmeniaClaw watches skill folders and bumps the snapshot when SKILL.md files change. Configure under skills.load:

json5

{  skills: {    load: {      extraDirs: ["~/Projects/agent-scripts/skills"],      allowSymlinkTargets: ["~/Projects/manager/skills"],      watch: true,      watchDebounceMs: 250,    },  },}

Use allowSymlinkTargets for intentional symlinked layouts where a skill root symlink points outside the configured root, for example <workspace>/skills/manager -> ~/Projects/manager/skills. Enable skills.workshop.allowSymlinkTargetWrites only when Skill Workshop should also apply proposals through those trusted symlinked paths.

Remote macOS nodes (Linux gateway)

If the Gateway runs on Linux but a macOS node is connected with system.run allowed, OmeniaClaw can treat macOS-only skills as eligible when the required binaries are present on that node. The agent should run those skills via the exec tool with host=node.

Offline nodes do not make remote-only skills visible. If a node stops answering bin probes, OmeniaClaw clears its cached bin matches.

Token impact

When skills are eligible, OmeniaClaw injects a compact XML block into the system prompt. The cost is deterministic:

text

total = 195 + Σ (97 + len(name) + len(description) + len(filepath))

Base overhead (only when ≥ 1 skill): ~195 characters
Per skill: ~97 characters + your name, description, and location field lengths
XML escaping expands & < > " ' into entities, adding a few characters per occurrence
At ~4 chars/token, 97 chars ≈ 24 tokens per skill before field lengths

Keep descriptions short and descriptive to minimize prompt overhead.

Creating skills

Step-by-step guide to authoring a custom skill.

Skill Workshop

Proposal queue for agent-drafted skills.

Skills config

Full skills.* config schema and agent allowlists.

Slash commands

How skill slash commands are registered and routed.

ClawHub

Browse and publish skills on the public registry.

Plugins

Plugins can ship skills alongside the tools they document.

Was this useful?

Loading order

Per-agent vs shared skills

Agent allowlists

Plugins and skills

Skill Workshop

Installing from ClawHub

Security

SKILL.md format

Optional frontmatter keys

Gating

Installer specs

Config overrides

Environment injection

Reads skill metadata

Injects env and API keys

Builds the system prompt

Restores the environment

Snapshots and refresh

Token impact

On this page

Molty

Loading order

Per-agent vs shared skills

Agent allowlists

Plugins and skills

Skill Workshop

Installing from ClawHub

Security

SKILL.md format

Optional frontmatter keys

Gating

Installer specs

Config overrides

Environment injection

Reads skill metadata

Injects env and API keys

Builds the system prompt

Restores the environment

Snapshots and refresh

Token impact

Related

On this page