Genesis Docs

Tools & Plugins / 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.

For how skills are loaded and prioritized, see Skills.

Create your first skill

Create the skill directory

Skills live in your workspace. Create a new folder:

mkdir -p ~/.genesis/workspace/skills/hello-world

Write SKILL.md

Create SKILL.md inside that directory. The frontmatter defines metadata, and the markdown body contains instructions for the agent.

---
name: hello_world
description: A simple skill that says hello.
---

# Hello World Skill

When the user asks for a greeting, use the `echo` tool to say
"Hello from your custom skill!".

Add tools (optional)

You can define custom tool schemas in the frontmatter or instruct the agent to use existing system tools (like exec or browser). Skills can also ship inside plugins alongside the tools they document.

Load the skill

Start a new session so Genesis picks up the skill:

# From chat
/new

# Or restart the gateway
genesis gateway restart

Verify the skill loaded:

genesis skills list

Test it

Send a message that should trigger the skill:

genesis agent --message "give me a greeting"

Or just chat with the agent and ask for a greeting.

Skill metadata reference

The YAML frontmatter supports these fields:

Field Required Description
name Yes Unique identifier (snake_case)
description Yes One-line description shown to the agent
metadata.genesis.os No OS filter (["darwin"], ["linux"], etc.)
metadata.genesis.requires.bins No Required binaries on PATH
metadata.genesis.requires.config No Required config keys

Best practices

  • Be concise — instruct the model on what to do, not how to be an AI
  • Safety first — if your skill uses exec, ensure prompts don't allow arbitrary command injection from untrusted input
  • Test locally — use genesis agent --message "..." to test before sharing
  • Use ClawHub — browse and contribute skills at ClawHub

Where skills live

Location Precedence Scope
\<workspace\>/skills/ Highest Per-agent
\<workspace\>/.agents/skills/ High Per-workspace agent
~/.agents/skills/ Medium Shared agent profile
~/.genesis/skills/ Medium Shared (all agents)
Bundled (shipped with Genesis) Low Global
skills.load.extraDirs Lowest Custom shared folders