# Skills

Agent skills that extend Claude's capabilities. Model-invoked (Claude decides when to use them).

## Available Skills

| Skill | Description | Scripts |
|-------|-------------|---------|
| `gmail` | Gmail read access | `check_unread.py`, `check_urgent.py`, `search.py` |
| `gcal` | Google Calendar access | `agenda.py`, `next_event.py` |
| `k8s-quick-status` | Kubernetes cluster health | `quick-status.sh` |
| `sysadmin-health` | Arch Linux health check | `health-check.sh` |
| `usage` | Session usage tracking | `usage_report.py` |
| `programmer-add-project` | Register projects | (workflow only) |

## Skill Structure

Each skill uses the "Resources Pattern":

```
skills/skill-name/
├── SKILL.md            # Main instructions (required)
├── scripts/            # Executable helpers
│   ├── action1.py
│   └── action2.sh
└── references/         # Documentation
    └── patterns.md
```

## Skill Format

```yaml
---
name: skill-name
description: What it does. Use when [trigger conditions].
allowed-tools:
  - Bash
  - Read
---

# Skill Name

## Quick Commands

```bash
./scripts/main-action.py [args]
```

## Request Routing

| User Request | Action |
|--------------|--------|
| "do X" | Run script with args |

## Policy

- Read-only / Write allowed
- Model tier preferences
```

## Key Elements

### Description

Critical for discovery. Include:
- What the skill does
- When Claude should use it (trigger phrases)

### allowed-tools

Restricts which tools Claude can use:
- `Bash` - Run commands/scripts
- `Read` - Read files
- `Write` - Write files
- `Edit` - Edit files

### Scripts

Standalone executables that do the work:
- Python: `#!/usr/bin/env python3`
- Bash: `#!/bin/bash`
- Must be executable: `chmod +x`

### References

Supporting documentation:
- Query patterns
- API reference
- Examples

## Adding a Skill

1. Create `skills/name/SKILL.md`
2. Add scripts to `skills/name/scripts/`
3. Make scripts executable
4. Update `component-registry.json` with triggers
5. Test: ask Claude something that should trigger it

## Skill vs Command

| Aspect | Skill | Command |
|--------|-------|---------|
| **Invocation** | Claude decides | User types `/command` |
| **Discovery** | Based on description | Explicit |
| **Use case** | Domain expertise | Quick actions |