@marcfargas/skills 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,106 @@
-# @marcfargas/skills
+# Skills
 
-Pi agent skills collection. Formal release coming soon.
+Reusable skills for AI coding agents. Works with [pi](https://github.com/mariozechner/pi-coding-agent), [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://cursor.sh), and any agent that supports the [Agent Skills standard](https://agentskills.io/specification).
+
+## Available Skills
+
+| Category | Skill | Description |
+|----------|-------|-------------|
+| ☁️ Google Cloud | [gcloud](google-cloud/gcloud/) | GCP CLI with agent safety model — hub + 7 reference files |
+| 🚀 Release | [pre-release](release/pre-release/) | Pre-release checklist + AI-written changesets via @changesets/cli |
+| 🎬 Terminal | [vhs](terminal/vhs/) | Record terminal sessions as GIF/MP4 with [VHS](https://github.com/charmbracelet/vhs) |
+
+## Install
+
+### One command (39+ agents)
+
+```bash
+npx skills add marcfargas/skills
+```
+
+Installs to Claude Code, Cursor, Copilot, Amp, Cline, Windsurf, Gemini CLI, and [30+ more agents](https://skills.sh) automatically.
+
+### pi
+
+```bash
+pi install npm:@marcfargas/skills
+```
+
+Or add to `~/.pi/agent/settings.json`:
+
+```json
+{
+  "packages": ["npm:@marcfargas/skills"]
+}
+```
+
+### Manual (any agent)
+
+Copy the skill directory into your agent's skill folder:
+
+```bash
+cp -r google-cloud/gcloud ~/.claude/skills/gcloud
+```
+
+## Skill Design Principles
+
+1. **Safety first** — destructive operations classified and gated, costs flagged
+2. **Hub + spoke** — thin SKILL.md hub (~140 lines) + per-topic reference files loaded on demand
+3. **Agent-native** — `--format=json` everywhere, idempotent patterns, error handling
+4. **Portable** — no hardcoded paths or personal config
+5. **Tested** — validated with Gemini, GPT, and Claude before publishing
+
+## Structure
+
+```
+skills/
+├── google-cloud/
+│   └── gcloud/          # 8 files, ~1100 lines total
+├── release/
+│   └── pre-release/     # 1 file
+├── terminal/
+│   └── vhs/             # 1 file
+└── README.md
+```
+
+## External Skills (planned)
+
+Some skills are developed in their own repositories and synced here:
+
+| Skill | Source Repo | Status |
+|-------|-------------|--------|
+| odoo | `odoo-toolbox` | Planned |
+| go-easy | `go-easy` | Planned |
+
+## Contributing
+
+Skills follow the [Agent Skills specification](https://agentskills.io/specification). Requirements:
+
+- `SKILL.md` with YAML frontmatter (`name`, `description`)
+- `name` matches parent directory (kebab-case, max 64 chars)
+- `description` present (max 1024 chars)
+- No hardcoded paths or credentials
+- Destructive operations clearly marked
+
+### Validation
+
+Use [skills-ref](https://github.com/agentskills/agentskills) (Python — the official reference implementation from the spec authors) to validate skills locally:
+
+```bash
+pip install skills-ref
+
+# Validate a skill directory
+agentskills validate path/to/skill
+
+# Read parsed properties as JSON
+agentskills read-properties path/to/skill
+
+# Generate <available_skills> XML prompt block
+agentskills to-prompt path/to/skill-a path/to/skill-b
+```
+
+CI runs `agentskills validate` on every push — see [`.github/workflows/validate.yml`](.github/workflows/validate.yml).
+
+## License
+
+MIT

package/google-cloud/gcloud/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: gcloud
+description: >-
+  Google Cloud Platform CLI (gcloud, gcloud storage, bq).
+  Use when: managing GCP resources, deploying to Cloud Run/Cloud Functions/GKE/App Engine,
+  working with Cloud Storage, BigQuery, IAM, Compute Engine, Cloud SQL, Pub/Sub,
+  Secret Manager, Artifact Registry, Cloud Build, Cloud Scheduler, Cloud Tasks,
+  Vertex AI, VPC/networking, DNS, logging/monitoring, or any GCP service.
+  Also covers: authentication, project/config management, CI/CD integration,
+  serverless deployments, container registry, docker push to GCP, managing secrets,
+  Workload Identity Federation, and infrastructure automation.
+---
+
+# gcloud — Google Cloud Platform CLI
+
+Command-line interface for managing Google Cloud resources.
+Covers `gcloud`, `gcloud storage` (replaces `gsutil`), and `bq` (BigQuery).
+
+## Platform Notes (Windows + Git Bash)
+
+- Install: `scoop install gcloud` (preferred) or `GoogleCloudSDKInstaller.exe`
+- If installed via scoop, `gcloud components install` may not work — use scoop to manage
+- Config: `%APPDATA%/gcloud/` (PowerShell) or `~/.config/gcloud/` (Git Bash)
+- Service account keys: store in `$TEMP` or project `.secrets/`, **never commit**
+- Python: gcloud requires Python; scoop install handles this automatically
+
+### ⚠️ Path Translation Gotcha
+
+Git Bash auto-translates `/`-prefixed args, breaking some gcloud commands:
+
+```bash
+# FIX — disable MSYS path conversion:
+export MSYS_NO_PATHCONV=1
+
+# Or per-command:
+MSYS_NO_PATHCONV=1 gcloud projects add-iam-policy-binding my-project ...
+```
+
+> **⚠️ Cost**: Commands that create resources (instances, clusters, databases) incur
+> GCP charges. Always confirm project and region before creating.
+
+## Agent Safety Model
+
+Operations classified by risk. **Follow this model for all gcloud commands.**
+
+| Level | Gate | Examples |
+|-------|------|----------|
+| **READ** | Proceed autonomously | `list`, `describe`, `get`, `logs read`, `config list`, `gcloud storage ls` |
+| **WRITE** | Confirm with user; note cost if billable | `create`, `deploy`, `update`, `enable`, `gcloud storage cp` (upload) |
+| **DESTRUCTIVE** | Always confirm; show what's affected | `delete`, `rm`, `gsutil rm -r`, `bq rm -r`, `rsync -d`, IAM removal |
+| **EXPENSIVE** | Confirm + state approximate cost | GKE clusters (~$70+/mo), SQL instances (~$8-400/mo), VMs (~$5-2k/mo) |
+| **SECURITY** | Confirm + explain impact | `--allow-unauthenticated`, firewall rules, IAM owner/editor grants |
+| **FORBIDDEN** | Refuse; escalate to human | `gcloud iam service-accounts keys create`, `gcloud projects delete`, passwords in CLI args |
+
+**Rules**:
+- **Never combine `--quiet` with destructive operations** — it suppresses the only safety gate
+- **Never put passwords/secrets as command-line arguments** — visible in process list & shell history
+- **Always use `--format=json`** for machine-parseable output (agents can't reliably parse tables)
+- **When in doubt, treat as DESTRUCTIVE**
+
+## Command Structure
+
+```
+gcloud [RELEASE_LEVEL] COMPONENT ENTITY OPERATION [ARGS] [FLAGS]
+```
+
+Key global flags: `--project`, `--format`, `--filter`, `--limit`, `--quiet`, `--verbosity`, `--async`
+
+## Service Reference
+
+| Service | File | Key Commands |
+|---------|------|-------------|
+| Auth & Config | [auth.md](auth.md) | Login, ADC, impersonation, config profiles |
+| IAM & Projects | [iam.md](iam.md) | Projects, APIs, service accounts, Secret Manager |
+| Compute & Networking | [compute.md](compute.md) | VMs, SSH, firewall, VPC, DNS, static IPs |
+| Serverless | [serverless.md](serverless.md) | Cloud Run, Functions, App Engine, Scheduler, Tasks |
+| Storage & Artifacts | [storage.md](storage.md) | gcloud storage, Artifact Registry |
+| Data | [data.md](data.md) | Cloud SQL, BigQuery (bq), Pub/Sub |
+| Automation & CI/CD | [automation.md](automation.md) | Scripting, output formats, filtering, GitHub Actions, operations |
+
+**Read the per-service file for full command reference.**
+
+## Pre-Flight Checks
+
+Before working with any GCP service:
+
+```bash
+# 1. Correct project?
+gcloud config get-value project
+
+# 2. Default region set?
+gcloud config get-value compute/region
+
+# 3. Required API enabled? (most APIs are disabled by default)
+gcloud services list --filter="name:run.googleapis.com" --format="value(name)" | grep -q run || \
+  gcloud services enable run.googleapis.com
+
+# 4. Billing enabled?
+gcloud billing projects describe $(gcloud config get-value project) --format="value(billingEnabled)"
+```
+
+**If you hit `PERMISSION_DENIED: ... API has not been enabled`**, enable the API
+mentioned in the error and retry.
+
+## Troubleshooting
+
+| Problem | Diagnosis | Fix |
+|---------|-----------|-----|
+| Auth failure | `gcloud auth list` | `gcloud auth login` or check key file |
+| Permission denied | Check IAM (see [iam.md](iam.md)) | Grant correct role |
+| API not enabled | Error message says which API | `gcloud services enable API_NAME` |
+| Quota exceeded | `gcloud compute project-info describe` | Request increase in Console |
+| Wrong project | `gcloud config get-value project` | `gcloud config set project X` |
+| Wrong region | `gcloud config get-value compute/region` | Set correct region; related resources must match |
+| Config confusion | `gcloud config configurations list` | Check active config, override with `--project` |
+| Slow commands | Large result set | Use `--filter`, `--limit`, `--format=value` |
+
+```bash
+# Debug mode
+gcloud compute instances list --verbosity=debug
+
+# Full environment info
+gcloud info
+```
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Login | `gcloud auth login` |
+| Set project | `gcloud config set project PROJECT_ID` |
+| Current project | `gcloud config get-value project` |
+| Enable API | `gcloud services enable API.googleapis.com` |
+| List anything | `gcloud COMPONENT list --format=json` |
+| Describe anything | `gcloud COMPONENT describe NAME --format=json` |
+| JSON output | `--format=json` |
+| Single value | `--format="value(field)"` |
+| Filter | `--filter="field=value"` |
+| Quiet ⚠️ | `--quiet` — suppresses ALL prompts including delete confirmations |
+| Help | `gcloud COMPONENT --help` |

package/google-cloud/gcloud/auth.md

@@ -0,0 +1,107 @@
+# Auth & Configuration
+
+## Authentication
+
+```bash
+# Interactive login (opens browser)
+gcloud auth login
+
+# Headless / remote
+gcloud auth login --no-browser
+
+# Check who's authenticated
+gcloud auth list
+
+# Revoke
+gcloud auth revoke user@example.com
+```
+
+## Service Account Impersonation (Preferred)
+
+**Always prefer impersonation over key files** — short-lived tokens, no key distribution risk.
+
+```bash
+# Single command
+gcloud compute instances list --impersonate-service-account=SA_EMAIL
+
+# Set as default
+gcloud config set auth/impersonate_service_account SA_EMAIL
+
+# Clear
+gcloud config unset auth/impersonate_service_account
+```
+
+## Application Default Credentials (ADC)
+
+For client libraries (Python, Node.js, Go, etc.):
+
+```bash
+# Set up ADC
+gcloud auth application-default login
+
+# With impersonation
+gcloud auth application-default login --impersonate-service-account=SA_EMAIL
+
+# Revoke
+gcloud auth application-default revoke
+```
+
+**ADC search order**:
+1. `GOOGLE_APPLICATION_CREDENTIALS` env var
+2. `~/.config/gcloud/application_default_credentials.json`
+3. GCE/GKE metadata server (when running on GCP)
+
+## Service Account (CI/CD only)
+
+```bash
+# Activate with key file (CI/CD environments)
+gcloud auth activate-service-account --key-file=key.json
+```
+
+> ⚠️ **Avoid key files when possible** — use Workload Identity Federation for
+> GitHub Actions, or impersonation for development. Key files are static
+> credentials that can leak.
+
+## Configuration Profiles
+
+Manage multiple environments without confusion:
+
+```bash
+# Create per-environment configs
+gcloud config configurations create dev
+gcloud config set project my-project-dev
+gcloud config set account dev@example.com
+gcloud config set compute/region europe-west1
+gcloud config set compute/zone europe-west1-b
+
+gcloud config configurations create prod
+gcloud config set project my-project-prod
+gcloud config set auth/impersonate_service_account prod-sa@project.iam.gserviceaccount.com
+
+# Switch environments
+gcloud config configurations activate dev
+gcloud config configurations list
+
+# One-off override (doesn't change active config)
+gcloud compute instances list --configuration=prod
+gcloud compute instances list --project=other-project
+
+# View current settings
+gcloud config list
+gcloud config get-value project
+gcloud config get-value compute/region
+```
+
+### Region/Zone Consistency
+
+Related GCP resources **must** be in the same region. Before creating any resource:
+
+```bash
+gcloud config get-value compute/region
+gcloud config get-value compute/zone
+```
+
+Common mismatches that cause failures:
+- VM in `europe-west1-b` connecting to Cloud SQL in `us-central1`
+- GKE cluster in one zone, persistent disks in another
+- Cloud Run in `europe-west1` accessing a VPC in `us-east1`

package/google-cloud/gcloud/automation.md

@@ -0,0 +1,165 @@
+# Automation, Scripting & CI/CD
+
+## Output Formats
+
+**Always use `--format=json` for agent consumption.** Table output breaks parsing.
+
+```bash
+gcloud compute instances list --format=json           # Full JSON
+gcloud compute instances list --format="value(name)"  # Raw values, one per line
+gcloud compute instances list --format="csv(name,zone,status)"
+gcloud compute instances list --format="table(name,zone.basename(),machineType.basename(),status)"
+```
+
+## Filtering
+
+```bash
+# Server-side (efficient — sent to API)
+gcloud compute instances list --filter="zone:europe-west1 AND status=RUNNING"
+gcloud compute instances list --filter="name~^web-.*"          # regex
+gcloud compute instances list --filter="NOT status=TERMINATED"
+gcloud compute instances list --filter="createTime>2026-01-01"
+
+# Combine with format + limit
+gcloud compute instances list \
+  --filter="status=RUNNING" \
+  --format="value(name)" \
+  --limit=10
+```
+
+## Idempotent Patterns
+
+```bash
+# Check-before-create
+if ! gcloud compute instances describe my-vm --zone=europe-west1-b &>/dev/null; then
+  gcloud compute instances create my-vm --zone=europe-west1-b --machine-type=e2-medium
+else
+  echo "Instance already exists"
+fi
+
+# Enable-if-not-enabled (safe to run multiple times)
+gcloud services enable compute.googleapis.com
+
+# Delete-if-exists (suppress error if already gone)
+gcloud compute instances delete my-vm --zone=europe-west1-b --quiet 2>/dev/null || true
+```
+
+## Error Handling
+
+```bash
+# Capture and check
+OUTPUT=$(gcloud compute instances create my-vm 2>&1)
+if [ $? -ne 0 ]; then
+  echo "Error: $OUTPUT" >&2
+  exit 1
+fi
+
+# Retry with backoff
+for i in 1 2 3 4 5; do
+  gcloud run deploy my-service --source=. --region=europe-west1 && break
+  echo "Attempt $i failed, retrying in $((i * 5))s..."
+  sleep $((i * 5))
+done
+```
+
+## Waiting for Long-Running Operations
+
+Many GCP operations (SQL instances, GKE clusters, deployments) take minutes.
+
+```bash
+# Option 1: Synchronous (default — blocks until done)
+# Most commands wait automatically. This is usually best.
+gcloud sql instances create my-db --database-version=POSTGRES_15 --tier=db-f1-micro --region=europe-west1
+
+# Option 2: Async + explicit wait
+gcloud compute instances create my-vm --zone=europe-west1-b --async --format="value(targetLink)"
+gcloud compute operations wait OPERATION_NAME --zone=europe-west1-b
+
+# Option 3: Poll pattern (for services without `wait`)
+OPERATION=$(gcloud sql operations list --instance=my-db --filter="status=RUNNING" --format="value(name)" --limit=1)
+while [ -n "$OPERATION" ]; do
+  STATUS=$(gcloud sql operations describe "$OPERATION" --format="value(status)")
+  if [[ "$STATUS" == "DONE" ]]; then
+    echo "Operation complete"
+    break
+  fi
+  echo "Status: $STATUS — waiting 10s..."
+  sleep 10
+done
+```
+
+**Agent note**: Default synchronous mode is usually best. Use `--async` only when
+parallelizing multiple independent operations.
+
+## Cloud Build
+
+```bash
+# Build and push container image
+gcloud builds submit --tag=europe-west1-docker.pkg.dev/PROJECT_ID/my-repo/my-image:tag .
+
+# Build with config
+gcloud builds submit --config=cloudbuild.yaml .
+
+# List builds
+gcloud builds list --format=json --limit=10
+
+# View build logs
+gcloud builds log BUILD_ID
+```
+
+## CI/CD: GitHub Actions
+
+### With Workload Identity Federation (preferred — no keys)
+
+```yaml
+- uses: google-github-actions/auth@v2
+  with:
+    workload_identity_provider: projects/PROJECT_NUM/locations/global/workloadIdentityPools/POOL/providers/PROVIDER
+    service_account: SA_EMAIL
+
+- uses: google-github-actions/setup-gcloud@v2
+
+- run: gcloud run deploy my-service --image=IMG:${{ github.sha }} --region=europe-west1
+```
+
+### With Service Account Key (fallback)
+
+```yaml
+- uses: google-github-actions/auth@v2
+  with:
+    credentials_json: ${{ secrets.GCP_SA_KEY }}
+
+- uses: google-github-actions/setup-gcloud@v2
+```
+
+## Environment Variables
+
+```bash
+# Make scripts portable
+PROJECT_ID="${GCP_PROJECT_ID:-my-default-project}"
+REGION="${GCP_REGION:-europe-west1}"
+
+gcloud config set project "$PROJECT_ID"
+gcloud config set compute/region "$REGION"
+```
+
+## Vertex AI (overview)
+
+```bash
+# List models
+gcloud ai models list --region=europe-west1 --format=json
+
+# List endpoints
+gcloud ai endpoints list --region=europe-west1 --format=json
+
+# Deploy model to endpoint
+gcloud ai endpoints deploy-model ENDPOINT_ID \
+  --model=MODEL_ID \
+  --region=europe-west1 \
+  --display-name="v1"
+
+# Predict
+gcloud ai endpoints predict ENDPOINT_ID \
+  --region=europe-west1 \
+  --json-request=request.json
+```

package/google-cloud/gcloud/compute.md

@@ -0,0 +1,113 @@
+# Compute Engine & Networking
+
+## Compute Engine
+
+```bash
+# READ — list instances
+gcloud compute instances list --format=json
+gcloud compute instances list --filter="status=RUNNING AND zone:europe-west1" --format=json
+
+# EXPENSIVE — create instance (~$5-2000+/mo depending on type)
+gcloud compute instances create my-vm \
+  --zone=europe-west1-b \
+  --machine-type=e2-medium \
+  --image-family=debian-12 \
+  --image-project=debian-cloud \
+  --boot-disk-size=20GB \
+  --tags=http-server
+
+# SSH (uses IAP tunneling by default — secure)
+gcloud compute ssh my-vm --zone=europe-west1-b
+gcloud compute ssh my-vm --zone=europe-west1-b --tunnel-through-iap  # explicit
+
+# SCP
+gcloud compute scp local.txt my-vm:~/remote.txt --zone=europe-west1-b
+
+# Lifecycle
+gcloud compute instances stop my-vm --zone=europe-west1-b
+gcloud compute instances start my-vm --zone=europe-west1-b
+
+# ⚠️ DESTRUCTIVE
+gcloud compute instances delete my-vm --zone=europe-west1-b
+```
+
+## Firewall Rules
+
+```bash
+# READ
+gcloud compute firewall-rules list --format=json
+
+# ⚠️ SECURITY — opens network ports
+gcloud compute firewall-rules create allow-http \
+  --allow=tcp:80 --target-tags=http-server --network=default
+
+gcloud compute firewall-rules create allow-https \
+  --allow=tcp:443 --target-tags=https-server --network=default
+
+# ⚠️ DESTRUCTIVE
+gcloud compute firewall-rules delete allow-http
+```
+
+## VPC & Subnets
+
+```bash
+# Create VPC
+gcloud compute networks create my-vpc --subnet-mode=auto
+gcloud compute networks list --format=json
+
+# Create subnet
+gcloud compute networks subnets create my-subnet \
+  --network=my-vpc --range=10.0.0.0/24 --region=europe-west1
+
+gcloud compute networks subnets list --format=json
+```
+
+## Static IPs
+
+```bash
+gcloud compute addresses create my-ip --region=europe-west1
+gcloud compute addresses list --format=json
+
+# ⚠️ Unattached static IPs cost ~$2.88/month
+```
+
+## DNS
+
+```bash
+gcloud dns managed-zones create my-zone \
+  --dns-name="example.com." --description="My zone"
+
+gcloud dns record-sets list --zone=my-zone --format=json
+
+# Add A record
+gcloud dns record-sets create www.example.com. \
+  --zone=my-zone --type=A --ttl=300 --rrdatas="1.2.3.4"
+```
+
+## Load Balancing (overview)
+
+```bash
+gcloud compute backend-services list --format=json
+gcloud compute url-maps list --format=json
+gcloud compute forwarding-rules list --format=json
+
+# ⚠️ EXPENSIVE — load balancers cost ~$18+/month
+```
+
+## Logging & Monitoring
+
+```bash
+# Read logs
+gcloud logging read "resource.type=gce_instance" --limit=20 --format=json
+gcloud logging read "severity>=ERROR AND timestamp>=\"$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)\"" --limit=50 --format=json
+
+# Tail logs (live)
+gcloud logging tail "resource.type=gce_instance"
+
+# Write log entry
+gcloud logging write my-log "Test message" --severity=INFO
+
+# Monitoring
+gcloud monitoring dashboards list --format=json
+gcloud monitoring policies list --format=json  # alert policies
+```