How to Extend Your AI Agent with Skills (Complete Guide)

Your AI agent is smart. It can reason, plan, and write. But without tools, it's like a carpenter without a hammer — lots of potential, no way to build anything.

Skills change that. A skill is a reusable module that gives your agent a specific capability: send emails, manage GitHub repos, search the web, control your calendar, scrape websites, or even automate other applications on your computer.

This guide covers everything you need to know about extending your AI agent with skills — what they are, how they work, and how to install and use them effectively.

1. What Are Agent Skills?

Think of skills as plugins for your AI agent. Each skill teaches the agent how to use a specific tool or perform a specific type of task.

Without a skill, your agent might know about GitHub — it can discuss pull requests and code review in theory. With the GitHub skill installed, your agent can actually create issues, review PRs, check CI status, and manage repositories.

The key insight: skills are instructions, not code. A skill is primarily a structured document (called SKILL.md) that tells the agent what tools are available, how to use them, and what patterns to follow. The agent reads this document and applies its reasoning to use the tools correctly.

This is fundamentally different from traditional plugins or extensions. Traditional plugins execute code. Skills provide context. The agent does the reasoning.

2. Anatomy of a Skill

Every skill follows the same structure:

my-skill/
├── SKILL.md          # The main instruction file (required)
├── scripts/          # Helper scripts the skill uses (optional)
│   └── helper.sh
└── references/       # Reference docs, templates (optional)
    └── api-docs.md

The SKILL.md file is the heart of every skill. It contains:

• Description: What the skill does and when to use it
• Prerequisites: What needs to be installed (CLI tools, API keys, etc.)
• Usage instructions: Step-by-step guide for the agent
• Examples: Common patterns and commands
• Edge cases: What to watch out for

Here's a simplified example of what a SKILL.md looks like:

# Weather Skill

## Description
Get current weather and forecasts via wttr.in or Open-Meteo.

## When to Use
User asks about weather, temperature, or forecasts for any location.

## Usage
```bash
# Quick weather for a city
curl "wttr.in/Seattle?format=3"

# Detailed forecast
curl "wttr.in/Seattle"
```

## Notes
- No API key needed
- Supports any city name or coordinates
- Default format is text, add ?format=j1 for JSON

When the agent encounters a weather-related request, it reads this document, understands the available commands, and executes the appropriate one. The agent adapts based on context — it might use the quick format for a casual question and the detailed format for a planning request.

3. Installing Skills

Skills can be installed from ClawHub (the community skill registry) or manually from GitHub:

From ClawHub (recommended)

# Search for skills
clawhub search "github"

# Install a skill
clawhub install deep-research-pro

# List installed skills
clawhub list

# Update a specific skill
clawhub update deep-research-pro

# Update all skills
clawhub update

Manual Installation

# Clone or download the skill to your skills directory
cd ~/.openclaw/skills/
git clone https://github.com/user/my-custom-skill.git

# The agent will auto-detect it on next session

After installation, the skill appears in your agent's available skills list. No restart needed — the agent picks it up on the next interaction.

4. Discovering Skills

Finding the right skill for your use case:

• TutuoAI Marketplace — Browse 117+ skills with categories, reviews, and use cases
• TutuoAI Discover — 38+ AI tools with agent integration guides
• ClawHub — clawhub search "keyword" from the command line
• Machine-readable index — /api/tool-discovery.json for programmatic discovery

The machine-readable index is particularly interesting: your agent can query it directly to discover what tools exist. This means the agent can self-extend — identify a capability gap, find a skill that fills it, and suggest installing it.

5. Using Skills Effectively

Once a skill is installed, you don't need to explicitly invoke it. The agent automatically matches your request to the appropriate skill based on context.

Example requests and which skills handle them:

The magic is in the matching. Your agent reads all available SKILL.md files and uses their descriptions to decide which skill applies. Write clear, natural requests, and the right skill activates.

6. Combining Skills for Complex Workflows

Skills become truly powerful when combined. Here are some real-world multi-skill workflows:

Morning Briefing (3 skills)

"Give me my morning briefing" — the agent combines:

• gog → Checks calendar for today's meetings and urgent emails
• weather → Pulls the forecast for your location
• finance_lite → Summarizes market moves overnight

One request, three skills, a complete briefing in 30 seconds.

Bug Fix Pipeline (3 skills)

"Fix the top 3 bugs in our repo" — the agent chains:

• github → Lists open issues labeled "bug", sorted by priority
• coding-agent → Spawns a sub-agent for each bug to write the fix
• github (again) → Opens PRs with the fixes, monitors CI

Content Research → Writing → Publishing (4 skills)

"Research trending topics in AI agents and draft a blog post":

• deep-research-pro → Researches the topic across multiple sources
• reddit → Checks what's trending in relevant subreddits
• Agent's built-in writing → Drafts the post
• obsidian → Saves the draft to your knowledge vault

7. Creating Your Own Skills

The skill format is intentionally simple. If you have a CLI tool or API that your agent should know about, you can create a skill in minutes:

1. Create the directory: mkdir ~/.openclaw/skills/my-skill
2. Write the SKILL.md: Describe what it does, when to use it, and how
3. Add helper scripts (optional): Put them in scripts/
4. Test it: Ask your agent to use the new capability

For a complete guide to skill authoring, including the skill-creator skill that helps you write skills, check the Resources page.

8. Best Practices

Start small

Don't install 50 skills at once. Start with 3-5 that match your daily workflow. Add more as you discover needs.

Read the SKILL.md

Before installing a skill, read its SKILL.md. Good skills document their prerequisites, limitations, and edge cases. Bad skills don't — and you'll waste time debugging.

Check prerequisites

Many skills need external tools installed (CLI tools, API keys, OAuth tokens). The SKILL.md should list these. Install them before expecting the skill to work.

Use heartbeats for monitoring

Skills like gog, weather, and github work great as periodic checks during agent heartbeats. Instead of manually asking "any new emails?" every hour, let the agent check automatically and notify you when something needs attention.

Contribute back

Found a bug in a skill? Fixed an edge case? Publish your improvement to ClawHub. The ecosystem gets better when everyone contributes.

Ready to explore? Browse the full skill catalog at TutuoAI Marketplace or check the Discover page for AI tools your agent can integrate with.

Last updated: March 9, 2026. This guide covers OpenClaw-compatible skills. The concepts apply to other agent frameworks that support skill/plugin architectures.