workspace/skills/<skill-id>/
├── SKILL.md          # Required: frontmatter + instructions
├── reference.md      # Optional: detailed docs
├── examples.md       # Optional: usage examples
└── scripts/          # Optional: helper scripts

---
name: my-skill
description: One-line summary. Use when the user asks for X or mentions Y.
metadata:
  openclaw:
    emoji: "🔧"
    requires:
      bins: ["jq", "curl"]
      env: ["API_KEY"]
---

# My Skill

Instructions, commands, and examples for the AI to follow.

metadata:
  openclaw:
    requires:
      bins: ["memo", "osascript"]  # Required binaries
      env: ["NOTION_API_KEY"]       # Required env vars

metadata:
  openclaw:
    install:
      - id: brew
        kind: brew
        formula: antoniorodr/memo/memo
        bins: ["memo"]
        label: Install memo via Homebrew

description: Manage Apple Notes via osascript and memo CLI. Use when the user asks to list notes, search notes, create a note, move notes, or delete notes.

description: Notion API for creating, reading, updating, and querying pages and databases. Use when the user mentions Notion, asks to save to Notion, or check a Notion board.

description: Helps with notes.

description: I can process Excel files and generate reports.

description: Apple Notes management.

# Apple Notes

Full Apple Notes management via `osascript` (all operations) and `memo` (quick listing).

**Key rule:** Always prefer `osascript` over `memo` for any write or move operation.

## List & Read

**List all notes (all folders):**
```bash
memo notes

osascript -e 'tell application "Notes" to get body of (first note of folder "Notes" whose name contains "Shopping")'

osascript -e 'tell application "Notes" to make new note at folder "Notes" with properties {name:"Title", body:"Content here"}'

This gives the AI:
- **Clear commands** it can copy
- **Section headers** for quick navigation
- **Real examples** (not placeholders)

## Complete Example: Weather Skill

Here's a minimal skill that uses wttr.in for weather:

```markdown
---
name: weather-wttr
description: Get weather forecasts using wttr.in. Use when the user asks about weather, temperature, or forecast for a location.
metadata:
  openclaw:
    emoji: "🌤️"
    requires:
      bins: ["curl"]
---

# Weather (wttr.in)

Get weather forecasts via wttr.in API.

## Current weather

```bash
curl "https://wttr.in/Tokyo?format=%l:+%C+%t+%w"

curl "https://wttr.in/London?format=3"

Save to `workspace/skills/weather-wttr/SKILL.md` and Asta will auto-detect it.

## Skill Discovery & Enabling

<Steps>
<Step title="Create the skill folder">
Create a new directory for your skill in the workspace skills directory:

- Run: `mkdir -p workspace/skills/myskill`
- Navigate: `cd workspace/skills/myskill`
</Step>

<Step title="Write SKILL.md">
Use the template above or copy an existing skill as a starting point.
</Step>

<Step title="Restart Asta (or reload skills)">
Asta scans workspace/skills at startup. Restart the backend with: `asta.sh restart`
</Step>

<Step title="Enable the skill in Settings">
1. Open Asta web panel: http://localhost:8000
2. Go to Settings → Skills
3. Find your skill and toggle it On
4. If dependencies are missing, Asta shows installation hints
</Step>
</Steps>

## Using Dependencies in Skills

### Binaries

If your skill needs a CLI tool, declare it in `requires.bins`:

```yaml
requires:
  bins: ["jq", "curl"]

requires:
  env: ["NOTION_API_KEY"]

curl -H "Authorization: Bearer $NOTION_API_KEY" https://api.notion.com/v1/...

## Create and update a Notion page

```bash
#!/bin/bash
set -e
KEY="$NOTION_API_KEY"
HDR=('-H' "Authorization: Bearer $KEY" '-H' 'Content-Type: application/json')

# Step 1: Create page
PAGE_ID=$(curl -s -X POST "https://api.notion.com/v1/pages" "${HDR[@]}" \
  -d '{"parent":{"database_id":"xxx"},"properties":{...}}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")

# Step 2: Add content
curl -s -X PATCH "https://api.notion.com/v1/blocks/$PAGE_ID/children" "${HDR[@]}" \
  -d '{"children":[{"object":"block","type":"paragraph",...}]}'

The AI will execute this as a single command, preserving state between steps.

## Referencing Other Files

Split long docs into separate files:

Link from SKILL.md:

```markdown
See [reference.md](reference.md) for full API details.