claude-code/skills/README.md

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

---
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 |