Skills
Creating skills
Skills teach the agent how and when to use tools. Each skill is a directory
containing a SKILL.md file with YAML frontmatter and markdown instructions.
OmeniaClaw loads skills from several roots in a defined precedence order.
Create your first skill
Create the skill directory
Skills live in your workspace skills/ folder. Create a directory for your
new skill:
mkdir -p ~/.OmeniaClaw/workspace/skills/hello-worldYou can group skills in subfolders for organization — the skill is still
named by the SKILL.md frontmatter, not the folder path:
mkdir -p ~/.OmeniaClaw/workspace/skills/personal/hello-world# skill name is still "hello-world", invoked as /hello-worldWrite SKILL.md
Create SKILL.md inside the directory. The frontmatter defines metadata;
the body gives the agent instructions.
---name: hello-worlddescription: A simple skill that prints a greeting.--- # Hello World When the user asks for a greeting, use the `exec` tool to run: ```bashecho "Hello from your custom skill!" Naming rules:- Use lowercase letters, digits, and hyphens for `name`.- Keep the directory name and frontmatter `name` aligned.- `description` is shown to the agent and in slash-command discovery — keep it one line and under 160 characters. OmeniaClaw_DOCS_MARKER:stepClose: OmeniaClaw_DOCS_MARKER:stepOpen:IHRpdGxlPSJWZXJpZnkgdGhlIHNraWxsIGxvYWRlZCI ```bashOmeniaClaw skills listOmeniaClaw watches SKILL.md files under skills roots by default. If the
watcher is disabled or you are continuing an existing session, start a new
one so the agent receives the refreshed list:
# From chat — archive current session and start fresh/new # Or restart the gatewayOmeniaClaw gateway restartTest it
Send a message that should trigger the skill:
OmeniaClaw agent --message "give me a greeting"Or open a chat and ask the agent directly. Use /skill hello-world to
invoke it explicitly by name.
SKILL.md reference
Required fields
| Field | Description |
|---|---|
name |
Unique slug using lowercase letters, digits, and hyphens |
description |
One-line description shown to the agent and in discovery output |
Optional frontmatter keys
| Field | Default | Description |
|---|---|---|
user-invocable |
true |
Expose the skill as a user slash command |
disable-model-invocation |
false |
Keep the skill out of the agent's system prompt (still runs via /skill) |
command-dispatch |
— | Set to tool to route the slash command directly to a tool, bypassing the model |
command-tool |
— | Tool name to invoke when command-dispatch: tool is set |
command-arg-mode |
raw |
For tool dispatch, forwards the raw args string to the tool |
homepage |
— | URL shown as "Website" in the macOS Skills UI |
For gating fields (requires.bins, requires.env, etc.) see
Skills — Gating.
Using {baseDir}
Use {baseDir} in the skill body to reference files inside the skill
directory without hardcoding paths:
Run the helper script at `{baseDir}/scripts/run.sh`.Adding conditional activation
Gate your skill so it only loads when its dependencies are available:
---name: gemini-searchdescription: Search using Gemini CLI.metadata: { "OmeniaClaw": { "requires": { "bins": ["gemini"] }, "primaryEnv": "GEMINI_API_KEY" } }---Gating options
| Key | Description |
|---|---|
requires.bins |
All binaries must exist on PATH |
requires.anyBins |
At least one binary must exist on PATH |
requires.env |
Each env var must exist in the process or config |
requires.config |
Each OmeniaClaw.json path must be truthy |
os |
Platform filter: ["darwin"], ["linux"], ["win32"] |
always |
Set true to skip all gates and always include the skill |
Full reference: Skills — Gating.
Environment and API keys
Wire an API key to a skill entry in OmeniaClaw.json:
{ skills: { entries: { "gemini-search": { enabled: true, apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, }, }, },}The key is injected into the host process for that agent turn only. It does not reach the sandbox — see sandboxed env vars.
Propose via Skill Workshop
For agent-drafted skills or when you want operator review before a skill goes
live, use Skill Workshop proposals instead of writing
SKILL.md directly.
# Propose a brand-new skillOmeniaClaw skills workshop propose-create \ --name "hello-world" \ --description "A simple skill that prints a greeting." \ --proposal ./PROPOSAL.md # Propose an update to an existing skillOmeniaClaw skills workshop propose-update hello-world \ --proposal ./PROPOSAL.md \ --description "Updated greeting skill"Use --proposal-dir when the proposal includes support files:
OmeniaClaw skills workshop propose-create \ --name "hello-world" \ --description "A simple skill that prints a greeting." \ --proposal-dir ./hello-world-proposal/The directory must contain PROPOSAL.md. Support files can go in assets/,
examples/, references/, scripts/, or templates/.
After review:
OmeniaClaw skills workshop inspect <proposal-id>OmeniaClaw skills workshop apply <proposal-id>See Skill Workshop for the full proposal lifecycle.
Publishing to ClawHub
Ensure your SKILL.md is complete
Make sure name, description, and any metadata.OmeniaClaw gating fields
are set. Add a homepage URL if you have a project page.
Install the ClawHub skill
The ClawHub skill documents the current publish command shape and required metadata:
OmeniaClaw skills install clawhub-publishPublish
clawhub publishSee ClawHub — Publishing for the full flow.
Best practices
Related
Loading order, gating, allowlists, and SKILL.md format.
Proposal queue for agent-drafted skills.
Full skills.* config schema.
Browse and publish skills on the public registry.
Plugins can ship skills alongside the tools they document.
