Your First Skill

The claw can talk. It can't do anything. Ask it "what's on my calendar?" and it'll guess or apologize. It has no access to your life.

A skill is a markdown file that teaches the claw how to use a tool. You write one, drop it in a skills/ directory, and the claw gains a capability it didn't have before. This is the pattern Andy used 193 times. joelclaw has 76. You're about to write your first.

Install gws

The gws CLI gives your claw access to Gmail, Google Calendar, Google Drive, Sheets. The entire Google Workspace via structured JSON output.

npm install -g @googleworkspace/cli

Then authenticate:

gws auth setup

This walks you through creating a Google Cloud project and OAuth credentials. It takes 10-15 minutes and requires enabling the Gmail and Calendar APIs. If you hit Error: invalid_grant, your OAuth consent screen may not be published. The gws README has a troubleshooting section. When done, verify:

gws --help

Read the output. The gws CLI wraps the Google Workspace APIs. Commands follow the API resource style. Test that it works:

gws gmail users messages list --params '{"userId": "me", "maxResults": 3}'

You should see message IDs from your actual inbox. Then test calendar:

gws calendar events list --params '{"calendarId": "primary", "timeMin": "'$(date -u +%Y-%m-%dT00:00:00Z)'", "singleEvents": true, "orderBy": "startTime"}'

Your actual calendar events. Real personal data, structured JSON.

Write the skill

Create skills/gws/SKILL.md:

# Google Workspace

You have access to Gmail and Google Calendar via the `gws` CLI.

## Email

gws gmail users messages list --params '{"userId": "me", "maxResults": 10}'
gws gmail users messages list --params '{"userId": "me", "q": "newer_than:1d"}'
gws gmail users messages get --params '{"userId": "me", "id": "<id>", "format": "metadata"}'

## Calendar

gws calendar events list --params '{"calendarId": "primary", "timeMin": "<ISO>", "timeMax": "<ISO>", "singleEvents": true, "orderBy": "startTime"}'

## When to Use

- "Check my email" → list recent messages, fetch metadata for each
- "What's on my calendar?" → list events for today
- "Send an email to..." → use gmail users messages send

Run gws --help to discover additional commands. The CLI wraps the Google Workspace APIs directly. All parameters are JSON via --params.

Update CLAUDE.md

Tell the claw about its new capability:

# My Claw

You are a personal assistant. Be concise and helpful.

## Skills

Check the `skills/` directory for available capabilities. Each skill is a
SKILL.md file that describes a tool and when to use it. Suggest relevant
skills when the operator's request matches.

You have access to the operator's Gmail and Google Calendar via the `gws` CLI.
When asked about email, calendar, or scheduling, use `gws` commands.

The ## Skills section is the claw's skill awareness. Every skill you add from now on gets picked up automatically because CLAUDE.md tells the claw to check the directory. The claw suggests skills when they're relevant instead of waiting for the operator to know what's available.

Permission configuration

Claude Code blocks Bash commands by default in headless mode. You need to tell it gws is allowed. Create .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(gws:*)"
    ],
    "deny": []
  }
}

Try it

node claw.mjs "What's on my calendar today?"

The claw runs gws calendar events list and tells you about your actual schedule. Not a guess. Your real data.

node claw.mjs "Any important emails?"

Your real inbox, triaged by the claw. This is the "oh shit" moment. Personal data in the response.

What you have

A claw with one skill that gives it access to your Google Workspace. The skill is a markdown file. No code, no plugin API, no configuration beyond the file itself. The pattern scales: write a skill for any CLI tool and the claw can use it.

Check your foundations

Before moving on, verify these. The next lessons build directly on them.

• node claw.mjs "What is 2+2?" returns a concise response
• node claw.mjs "What did I just ask?" remembers (session works)
• node claw.mjs "What's on my calendar?" runs gws and returns real data
• skills/gws/SKILL.md exists with command mappings

What's missing

Every question hits the live API. Ask "what's on my calendar?" twice and it makes two API calls. Slow and wasteful. Next, you teach the claw to gather context in the background so it already knows the answer when you ask.