Genesis Docs

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:

```bash
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.

```markdown
---
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:

```bash
# From chat
/new

# Or restart the gateway
genesis gateway restart
```

Verify the skill loaded:

```bash
genesis skills list
```

Test it

Send a message that should trigger the skill:

```bash
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

Related