> ## Documentation Index
> Fetch the complete documentation index at: https://agdiai-597e782f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating 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](https://agdiai-597e782f.mintlify.site/tools/skills.md).

## Create your first skill

**1. Create the skill directory**

Skills live in your workspace. Create a new folder:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
mkdir -p ~/.agdi/workspace/skills/hello-world
```

**2. Write SKILL.md**

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

```markdown theme={"theme":{"light":"min-light","dark":"min-dark"}}
---
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!".
```

**3. 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.

**4. Load the skill**

Start a new session so Agdi picks up the skill:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# From chat
/new

# Or restart the gateway
agdi gateway restart
```

Verify the skill loaded:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi skills list
```

**5. Test it**

Send a message that should trigger the skill:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
agdi 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.agdi.os` | No | OS filter (`["darwin"]`, `["linux"]`, etc.) |
| `metadata.agdi.requires.bins` | No | Required binaries on PATH |
| `metadata.agdi.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 `agdi agent --message "..."` to test before sharing
* **Use ClawHub** — browse and contribute skills at [ClawHub](https://clawhub.com)

## Where skills live

| Location | Precedence | Scope |
| - | - | - |
| `\<workspace\>/skills/` | Highest | Per-agent |
| `~/.agdi/skills/` | Medium | Shared (all agents) |
| Bundled (shipped with Agdi) | Lowest | Global |
| `skills.load.extraDirs` | Lowest | Custom shared folders |

## Related

* [Skills reference](https://agdiai-597e782f.mintlify.site/tools/skills.md) — loading, precedence, and gating rules
* [Skills config](https://agdiai-597e782f.mintlify.site/tools/skills-config.md) — `skills.*` config schema
* [ClawHub](https://agdiai-597e782f.mintlify.site/tools/clawhub.md) — public skill registry
* [Building Plugins](https://agdiai-597e782f.mintlify.site/plugins/building-plugins.md) — plugins can ship skills


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.