Creating Custom Skills

Skills are markdown instruction files that teach your agent how to perform specific tasks. Unlike plugins (which add new tools), skills are pure documentation — they guide your agent on how to use its existing tools for a particular workflow.

Every skill lives in a SKILL.md file with YAML frontmatter and markdown instructions.

How Skills Work

When a skill is installed on your agent, Agento deploys the SKILL.md file into the agent's container. Your agent reads it as part of its context and follows the instructions when relevant tasks come up.

Skills can teach your agent things like:

• How to interact with a specific API (e.g., Trello, Pipedrive, Google Calendar)
• Step-by-step workflows (e.g., customer onboarding checklist)
• Domain-specific knowledge (e.g., coding conventions, support playbooks)
• Tool usage patterns (e.g., how to use a CLI tool installed in the container)

SKILL.md Format

Every skill needs a SKILL.md file with YAML frontmatter at the top. Without the frontmatter, OpenClaw silently ignores the skill.

Minimal Example

---
name: my-custom-skill
description: "Brief description of what this skill does"
---

# My Custom Skill

Instructions for your agent go here.

## Commands

Teach your agent specific commands or API calls:

\`\`\`bash
curl -X GET "https://api.example.com/data" \
  -H "Authorization: Bearer $EXAMPLE_API_KEY"
\`\`\`

## When to Use

- Describe scenarios where this skill applies
- Help the agent understand context triggers

Full Example — Trello Integration

---
name: trello
description: "Manage Trello boards, lists, and cards via the REST API"
metadata:
  clawdbot:
    requires:
      bins: ["curl", "jq"]
---

# Trello

Manage Trello boards, lists, and cards. Uses the Trello REST API
with `$TRELLO_API_KEY` and `$TRELLO_TOKEN` environment variables.

## Authentication

All requests require these query parameters:
- `key=$TRELLO_API_KEY`
- `token=$TRELLO_TOKEN`

## Common Operations

### List All Boards

\`\`\`bash
curl -s "https://api.trello.com/1/members/me/boards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" | jq '.[].name'
\`\`\`

### Get Cards on a Board

\`\`\`bash
curl -s "https://api.trello.com/1/boards/{boardId}/cards?key=$TRELLO_API_KEY&token=$TRELLO_TOKEN" | jq '.[] | {name, id, idList}'
\`\`\`

### Create a Card

\`\`\`bash
curl -X POST "https://api.trello.com/1/cards" \
  -d "key=$TRELLO_API_KEY" \
  -d "token=$TRELLO_TOKEN" \
  -d "idList={listId}" \
  -d "name=Card title" \
  -d "desc=Card description"
\`\`\`

### Move a Card

\`\`\`bash
curl -X PUT "https://api.trello.com/1/cards/{cardId}" \
  -d "key=$TRELLO_API_KEY" \
  -d "token=$TRELLO_TOKEN" \
  -d "idList={targetListId}"
\`\`\`

## When to Use

- User asks about tasks, boards, or project management
- Moving items between lists (e.g., "move the Acme card to Done")
- Creating new cards from conversations or action items

Frontmatter Reference

Field	Required	Description
name	Yes	Unique skill identifier (lowercase, hyphens allowed)
description	Yes	One-line description of the skill
metadata.clawdbot.requires.bins	No	Required binaries (e.g., ["curl", "jq", "python3"])
metadata.clawdbot.requires.anyBins	No	At least one must be available (e.g., ["npm", "pnpm", "yarn"])
metadata.clawdbot.install	No	Auto-install instructions for missing dependencies

Installing Custom Skills

There are three ways to add skills to your agent:

1. From the Skills Marketplace

Browse verified and community skills directly from your agent's dashboard. These are pre-vetted and ready to install with one click.

2. From a GitHub Repository

If you've published your skill to a GitHub repository, you can install it as a custom skill:

1. Your repository must contain an openclaw.plugin.json manifest:

{
  "id": "my-custom-skill",
  "name": "My Custom Skill",
  "version": "1.0.0",
  "description": "What this skill does",
  "channels": [],
  "configSchema": {}
}

2. The repository must also contain a SKILL.md file with proper frontmatter.

3. Install via the API:

curl -X POST "https://hub.agento.host/agents/{agentId}/skills" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "skillId": "my-custom-skill",
    "trustLevel": "custom",
    "customSource": "https://github.com/your-username/your-skill-repo"
  }'

4. Restart your agent for the skill to take effect.

3. Writing Inline Skills (Power Users)

For quick, personal skills that don't need a GitHub repository, you can write the SKILL.md content directly and have your agent save it to its skills directory:

1. Chat with your agent and ask it to create a skill:

"Create a new skill called daily-standup that reminds the team about standup format: what you did yesterday, what you're doing today, and any blockers."

2. Your agent will create the file at ~/.openclaw/skills/daily-standup/SKILL.md with proper frontmatter.

3. The skill persists across restarts — agent-created skills in ~/.openclaw/skills/ are preserved automatically.

Tips for Writing Good Skills

Be specific with commands. Show exact curl commands, CLI invocations, or code snippets. Don't just describe what to do — show it.

Include environment variables. If the skill needs API keys, reference them as $ENV_VAR_NAME and document which ones are required. Add the env vars to your agent's configuration.

Add "When to Use" sections. Help your agent understand when to apply the skill, not just how. This improves accuracy — the agent won't try to use Trello commands when you're asking about something else.

Keep it focused. One skill = one capability. A Trello skill shouldn't also handle Slack. Split them into separate skills.

Test iteratively. After installing a skill, chat with your agent and ask it to perform the task. If it misunderstands something, refine the instructions.

Environment Variables

Many skills need API keys or tokens. Add these to your agent's environment variables in the dashboard under Settings → Environment Variables.

Common patterns:

Skill	Required Env Vars
Trello	TRELLO_API_KEY, TRELLO_TOKEN
Brave Search	BRAVE_API_KEY
Custom APIs	YOUR_SERVICE_API_KEY

Your agent can reference these in commands using $VAR_NAME syntax.

Importing Skills from Another Agent

If you're migrating from a self-hosted OpenClaw instance, you can transfer skills:

1. On the source machine, list installed skills:

ls ~/.openclaw/skills/

2. Copy each SKILL.md to your new agent. You can either:

   • Paste the content into a chat message and ask your agent to save it
   • Use the API to install the skill from a GitHub repo
   • SSH into the host node and copy files directly into /opt/agents/{agentId}/config/skills/

3. Restart your agent to load the new skills.