opencode-skills-collection 4.0.0 → 4.0.1

package/bundled-skills/apple-container/references/workflows.md

@@ -0,0 +1,498 @@
+# `container` — Task-Oriented Workflows
+
+Copy-pasteable recipes for Apple's `container` CLI (`apple/container`) — Linux containers as
+lightweight VMs on Apple-silicon macOS. This is **Apple's `container`, not Docker**: flags,
+defaults, and the daemon model differ. See `commands.md` for the full flag reference. Use
+fully-qualified image refs (`docker.io/library/alpine`) in scripts. `container` targets
+**macOS 26**; several features are gated (called out inline).
+
+> **Version:** recipes track the **1.0.0** release. `container cp`, `container prune`,
+> `container image prune`, and `container system version` used below were added in 1.0.0 (not in
+> 0.7.1) — run `container --help` to confirm your installed surface.
+
+## Recipes
+
+- [First run: install + start + first container](#first-run-install--start--first-container)
+- [Run interactive vs detached](#run-interactive-vs-detached)
+- [Publish ports](#publish-ports)
+- [Set environment variables](#set-environment-variables)
+- [Mounts: bind, volume, tmpfs](#mounts-bind-volume-tmpfs)
+- [Build an image from a Dockerfile](#build-an-image-from-a-dockerfile)
+- [Multi-tag, build-args, no-cache, target](#multi-tag-build-args-no-cache-target)
+- [Tag & push to Docker Hub / private registry](#tag--push-to-docker-hub--private-registry)
+- [Set the default registry](#set-the-default-registry)
+- [Container-to-container networking](#container-to-container-networking)
+- [Local DNS domain for name resolution](#local-dns-domain-for-name-resolution)
+- [Custom isolated networks (macOS 26)](#custom-isolated-networks-macos-26)
+- [Inspect a container](#inspect-a-container)
+- [View logs](#view-logs)
+- [Exec into a running container](#exec-into-a-running-container)
+- [Copy files in and out](#copy-files-in-and-out)
+- [Resource limits (CPU / memory)](#resource-limits-cpu--memory)
+- [Cleanup: stop, remove, prune](#cleanup-stop-remove-prune)
+- [Upgrade / downgrade / uninstall](#upgrade--downgrade--uninstall)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+### First run: install + start + first container
+
+There is **no CLI installer command** — download and double-click the signed `.pkg`, then start
+the services and run a container.
+
+```bash
+# 1. Download the signed installer .pkg from the GitHub releases page:
+#    https://github.com/apple/container/releases
+#    Double-click the .pkg and follow the prompts (admin password installs under /usr/local).
+
+# 2. Start the background services. On first run this prompts to install the default Linux kernel.
+container system start
+
+# 3. Verify (empty list is expected on a fresh install).
+container list --all
+
+# 4. Run your first container.
+container run --rm -it docker.io/library/alpine:latest sh
+```
+
+Note: double-clicking the `.pkg` is the only install path; `container system start` prompts for the recommended kernel (or use `container system kernel set --recommended`).
+
+---
+
+### Run interactive vs detached
+
+```bash
+# Interactive shell (-i keeps stdin open, -t allocates a TTY; commonly combined as -it).
+container run --rm -it docker.io/library/ubuntu:latest /bin/bash
+
+# Detached, named, auto-removed on stop.
+container run -d --name web --rm docker.io/library/nginx:latest
+
+# One-shot command in the foreground (exits when the command finishes).
+container run --rm docker.io/library/alpine:latest uname -a
+```
+
+Note: foreground by default; stdin stays closed unless `-i`. `--rm` deletes the container after it exits.
+
+---
+
+### Publish ports
+
+`-p` / `--publish` forwards loopback traffic to the container. Spec: `[host-ip:]host-port:container-port[/protocol]` (`tcp`/`udp`, case-insensitive).
+
+```bash
+# host 8080 -> container 80
+container run -d --rm -p 8080:80 docker.io/library/nginx:latest
+
+# bind to a specific host IP
+container run -d --rm -p 127.0.0.1:8080:8000 docker.io/library/node:latest npx http-server -a :: -p 8000
+
+# IPv6 loopback (quote the bracketed address)
+container run -d --rm -p '[::1]:8080:8000' docker.io/library/node:latest npx http-server -a :: -p 8000
+
+# UDP
+container run -d --rm -p 5353:5353/udp docker.io/library/alpine:latest
+```
+
+Note: if a container attaches to multiple networks, published ports forward to the IP of the first network's interface.
+
+---
+
+### Set environment variables
+
+```bash
+# Individual vars (-e / --env); repeatable. Bare `KEY` inherits from the host.
+container run --rm -e NODE_ENV=production -e PORT=8080 docker.io/library/node:latest env
+
+# Inherit HOME from the host shell
+container run --rm -e HOME docker.io/library/alpine:latest sh -c 'echo $HOME'
+
+# From a file (KEY=value per line; # comments and blanks ignored); repeatable.
+container run --rm --env-file ./app.env docker.io/library/alpine:latest env
+```
+
+Note: `-e` and `--env-file` may be combined and each repeated; later values win.
+
+---
+
+### Mounts: bind, volume, tmpfs
+
+```bash
+# Bind-mount a host folder (-v host:container). Use absolute host paths.
+container run --rm -v "${HOME}/Desktop/assets:/content/assets" docker.io/library/python:alpine ls -l /content/assets
+
+# Same via --mount key=value syntax.
+container run --rm --mount source="${HOME}/Desktop/assets",target=/content/assets docker.io/library/python:alpine ls /content/assets
+
+# Named volume (create first, then mount by name).
+container volume create data
+container run --rm -v data:/var/lib/app docker.io/library/alpine:latest sh
+
+# Anonymous volume (-v /path) — NOT auto-removed by --rm; delete it yourself.
+container run --rm -v /data docker.io/library/alpine:latest sh
+# It leaves an anon-<id> volume. List to find the exact name, then remove THAT one by name:
+container volume list          # locate the new anon-<id> row
+container volume rm anon-<id>  # ⚠️ delete the specific volume — do NOT `grep anon | rm`, which
+                              #    would match (and destroy) every anonymous volume on the machine
+
+# Read-only bind via --mount.
+container run --rm --mount type=bind,source="${PWD}/conf",target=/etc/conf,readonly docker.io/library/alpine:latest cat /etc/conf/app.ini
+
+# tmpfs (in-memory) mount; repeatable.
+container run --rm --tmpfs /scratch docker.io/library/alpine:latest sh -c 'df -h /scratch'
+```
+
+Note: unlike Docker, anonymous volumes do not auto-clean with `--rm` — remove them via `container volume rm`.
+
+---
+
+### Build an image from a Dockerfile
+
+```bash
+# Build from ./Dockerfile in the current context, tag as web-test.
+container build -t web-test .
+
+# Explicit Dockerfile path.
+container build -f docker/Dockerfile.prod -t web-test:prod .
+
+# Build, then run it.
+container build -t web-test .
+container run -d --name my-web-server --rm web-test
+```
+
+Note: with no `-f`, the builder looks for `Dockerfile` then `Containerfile`. The builder runs in its own VM (see resource-limits recipe to size it).
+
+---
+
+### Multi-tag, build-args, no-cache, target
+
+```bash
+# Multiple tags on one build (-t repeatable).
+container build -t my-app:latest -t my-app:v1.0.0 .
+
+# Build-time variables (repeatable).
+container build --build-arg NODE_VERSION=18 --build-arg ENV=prod -t my-app .
+
+# Skip the build cache.
+container build --no-cache -t my-app .
+
+# Target a specific multi-stage build stage.
+container build --target production -t my-app:prod .
+
+# Multi-architecture image (arm64 + amd64 via Rosetta).
+container build --arch arm64 --arch amd64 -t docker.io/me/web-test:latest .
+```
+
+Note: `--arch` is repeatable/comma-separated; `--platform` (`os/arch[/variant]`) takes precedence over `--os`/`--arch`.
+
+---
+
+### Tag & push to Docker Hub / private registry
+
+Registry commands live under the **Image** group (`container registry`, alias `r`). Credentials are stored in the macOS keychain.
+
+```bash
+# Log in (prompts for username + password, or use -u / --password-stdin).
+container registry login docker.io
+container registry login -u alice ghcr.io
+echo "$TOKEN" | container registry login -u alice --password-stdin ghcr.io
+
+# HTTP for a local registry.
+container registry login --scheme http localhost:5000
+
+# Tag the local image with a full registry reference.
+container image tag web-test docker.io/alice/web-test:latest
+
+# Push it (the final reference is printed on success).
+container image push docker.io/alice/web-test:latest
+
+# Private registry.
+container image tag web-test registry.example.com/fido/web-test:latest
+container image push registry.example.com/fido/web-test:latest
+
+# List saved logins / log out.
+container registry list   # 1.0.0+ (added after 0.7.1)
+container registry logout ghcr.io
+```
+
+Note: the default registry is `docker.io`, so a bare `web-test:latest` resolves against Docker Hub. Change it via the `registry.domain` property (next recipe).
+
+---
+
+### Set the default registry
+
+```bash
+# Inspect current properties (includes [registry] domain).
+container system property list
+```
+
+Edit `~/.config/container/config.toml`:
+
+```toml
+[registry]
+domain = "registry.example.com"
+```
+
+Note: with `registry.domain` set, unqualified image names resolve against that host instead of `docker.io`.
+
+---
+
+### Container-to-container networking
+
+Each container gets its own IP on the `default` vmnet network. Read it from `container ls` or `container inspect`.
+
+```bash
+# Start a server, then find its IP.
+container run -d --name my-web-server --rm web-test
+container ls                       # IP column shows e.g. 192.168.64.3
+
+# Scriptable IP lookup via inspect + jq.
+container inspect my-web-server | jq -r '.[0].networks[0].address'
+
+# Reach it from another container by IP (requires macOS 26 — see note).
+container run --rm -it web-test curl http://192.168.64.3
+```
+
+Note: container-to-container access over the virtual network requires macOS 26 and **does not work on macOS 15**, where containers are isolated from one another at the network layer (see `concepts.md` §3) — a naming scheme cannot restore connectivity. The DNS domain in the next recipe resolves names **host-side only** (host → container); it does not enable container-to-container traffic on macOS 15.
+
+---
+
+### Local DNS domain for name resolution
+
+Register a local domain so `<name>.<domain>` resolves to a named container's IP. `dns create`/`delete` need `sudo` (writes under `/etc/resolver`).
+
+```bash
+# Create the domain (admin password required).
+sudo container system dns create test
+```
+
+Make it the default DNS domain by setting `dns.domain` in `~/.config/container/config.toml`
+(there is no `property set` command — properties are edited in the config file):
+
+```toml
+[dns]
+domain = "test"
+```
+
+```bash
+# Now a named container is reachable as <name>.<domain>.
+container run -d --name my-web-server --rm web-test
+curl http://my-web-server.test
+
+# List / remove domains.
+container system dns list
+sudo container system dns delete test
+
+# Confirm the effective domain.
+container system property list        # shows [dns] domain = "test"
+```
+
+Note: `container system property` only supports `list`/`ls` — set `dns.domain` via `config.toml`, not a CLI setter. A container named `my-web-server` with domain `test` answers at `my-web-server.test`.
+
+---
+
+### Custom isolated networks (macOS 26)
+
+The entire `container network` group **requires macOS 26** (absent on macOS 15, which has only the single default subnet).
+
+```bash
+# Create an isolated network.
+container network create foo
+
+# With custom subnets.
+container network create foo --subnet 192.168.100.0/24 --subnet-v6 fd00:1234::/64
+
+# Attach a container to it.
+container run -d --name my-web-server --network foo --rm web-test
+
+# List / delete (detach all containers first).
+container network list
+container stop my-web-server
+container network delete foo
+```
+
+Note: networks are mutually isolated — a container on `foo` has no connectivity to containers on `default`.
+
+---
+
+### Inspect a container
+
+```bash
+# Full pretty JSON (one or more IDs).
+container inspect my-web-server
+
+# Extract specific fields with jq.
+container inspect my-web-server | jq -r '.[0].status'
+container inspect my-web-server | jq -r '.[0].networks[0].address'
+
+# Table/JSON listing of all containers, including stopped.
+container ls --all
+container ls --all --format json | jq '.[] | [.configuration.id, .networks[0].address]'
+```
+
+Note: `inspect` requires at least one ID; a missing ID errors. `container image inspect <ref>` does the same for images.
+
+---
+
+### View logs
+
+```bash
+# Application stdio.
+container logs my-web-server
+
+# Follow live output.
+container logs -f my-web-server
+
+# Last N lines (-n is short-only; there is no --lines).
+container logs -n 100 my-web-server
+
+# VM boot / init logs.
+container logs --boot my-web-server
+```
+
+Note: `--boot` shows the VM kernel + `vminitd` init log, useful for boot/networking diagnostics.
+
+---
+
+### Exec into a running container
+
+```bash
+# Interactive shell in a running container.
+container exec -it my-web-server sh
+
+# One-off command.
+container exec my-web-server ls /content
+
+# With env / as a specific user.
+container exec -e DEBUG=1 -u root my-web-server env
+```
+
+Note: `exec` targets a **running** container and shares the same process options as `run` (`-e`, `--env-file`, `-u`, `-w`, etc.).
+
+---
+
+### Copy files in and out
+
+Exactly one side must be a `container_id:path` reference. The container must be running.
+
+```bash
+# Host -> container.
+container cp ./config.json my-web-server:/etc/app/
+
+# Container -> host.
+container cp my-web-server:/var/log/app.log ./logs/
+```
+
+Note: `container copy` and `container cp` are the same command.
+
+---
+
+### Resource limits (CPU / memory)
+
+Container defaults: 4 CPUs, 1 GiB RAM. Builder VM defaults: 2 CPUs, 2 GiB RAM.
+
+```bash
+# Per-container limits on run/create.
+container run --rm --cpus 8 --memory 32g docker.io/library/alpine:latest sh
+
+# Short flags.
+container run --rm -c 2 -m 1G docker.io/library/node:latest
+
+# Size the builder VM before a heavy build.
+container builder start --cpus 8 --memory 32g
+container build -t big-app .
+
+# Change a running builder: stop, delete, restart with new limits.
+# ⚠️ `builder delete` discards the BuildKit builder and its layer cache — the next build
+#    re-fetches base images and rebuilds every layer from scratch.
+container builder stop
+container builder delete
+container builder start --cpus 8 --memory 32g
+```
+
+Note: memory accepts `K`/`M`/`G`/`T`/`P` suffixes. Monitor live usage with `container stats` (`--no-stream` for a single snapshot).
+
+---
+
+### Cleanup: stop, remove, prune
+
+> **⚠️ Scope matters.** The `-a`/`--all`/`prune` variants act on **every** container, image,
+> volume, or network on the machine — not just this project's. `container volume prune` and
+> `container image rm --all` permanently delete data belonging to *unrelated* containers. To clean
+> up after one workload, use the **targeted** commands (by name/tag); reach for the machine-wide
+> ones only when you deliberately want a full sweep. Do not paste this whole block blindly.
+
+```bash
+# --- Targeted (scoped to named resources — safe for cleaning up one workload) ---
+container stop my-web-server            # stop one container
+container delete my-web-server          # rm is an alias; add -f to remove a running one
+container image delete web-test         # remove one image by name/tag
+container volume rm data                # remove one volume by name
+
+# --- Machine-wide (destroys ALL matching resources — use deliberately) ---
+container stop -a                       # stop every running container
+container rm --all                      # delete every container
+container image rm --all                # delete every image
+container image prune                   # remove dangling (untagged) images only
+container image prune -a                # remove every image not used by a container
+container volume prune                  # delete every volume with no container reference
+container network prune                 # macOS 26+; delete every unused network
+container prune                         # remove all stopped containers
+
+# Check disk usage across images/containers/volumes.
+container system df
+```
+
+Note: `container prune` only removes **stopped** containers. `image prune` (no `-a`) removes only dangling images.
+
+---
+
+### Upgrade / downgrade / uninstall
+
+Both scripts install to `/usr/local/bin`. **Stop the services first.**
+
+```bash
+# Always stop before upgrading/downgrading.
+container system stop
+
+# Upgrade to the latest release.
+/usr/local/bin/update-container.sh
+
+# Downgrade: uninstall (keep user data with -k), then pin the previous release.
+/usr/local/bin/uninstall-container.sh -k
+/usr/local/bin/update-container.sh -v 0.7.1   # replace with the version you want
+
+# Restart after any change.
+container system start
+
+# Uninstall. Default to -k (keep user data) unless you truly want everything gone.
+/usr/local/bin/uninstall-container.sh -k      # keep images/containers/volumes for a later reinstall
+/usr/local/bin/uninstall-container.sh -d      # ⚠️ also deletes ALL user data (images, containers, volumes) — irreversible
+```
+
+Note: you can also upgrade/downgrade by re-downloading and double-clicking the signed `.pkg`. `-v` pins `update-container.sh` to a specific version.
+
+---
+
+### Troubleshooting
+
+```bash
+# "XPC connection error" / commands hang -> services aren't running. Start them.
+container system start
+
+# Confirm services are up.
+container system status
+
+# View service logs (default last 5m; --last <n>[m|h|d], -f to follow).
+container system logs
+container system logs --last 1h
+container system logs -f
+
+# Add --debug to any command for verbose output (or set CONTAINER_DEBUG).
+container --debug run --rm docker.io/library/alpine:latest true
+
+# Version info for CLI + API server.
+container system version
+```
+
+Note: an XPC/connection error means the background API server isn't started — run `container system start`. Feature gates to keep in mind: container-to-container access and the `container network` group require **macOS 26** (both unavailable on **macOS 15**). The CLI refuses to run under Rosetta — Apple silicon only.

package/bundled-skills/ask-copilot/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: ask-copilot
+description: "Use GitHub Copilot CLI in non-interactive mode to ask questions, review code, or generate snippets without manual interaction."
+category: development
+risk: critical
+source: self
+source_repo: cshara1/antigravity-awesome-skills
+source_type: self
+date_added: "2026-07-08"
+author: cshara1
+tags: [copilot, github, cli, review, prompt]
+tools: [claude, cursor, gemini]
+---
+
+# Ask Copilot
+
+## Overview
+
+This skill allows the agent to interact with GitHub Copilot CLI (`copilot`) in a non-interactive (headless) mode. Use this skill when the user explicitly wants secondary advice, code reviews, explanations, or code generation from GitHub Copilot's models.
+
+Use `source: self` and `source_type: self` when the skill is original to this repository and does not require README external-source credit.
+
+Copilot is an external service. Treat prompts, file paths, snippets, repository content, command output, and generated suggestions as data that may leave the local environment.
+
+## When to Use This Skill
+
+- **User Request Only**: Use this skill **ONLY** when the user explicitly asks to "consult Copilot", "ask Copilot", "review with Copilot", or explicitly requests a second opinion using Copilot.
+- **Do NOT Invoke Automatically**: To comply with privacy policies, the agent must not invoke this skill automatically for its own second opinions or checks without explicit user consent.
+
+## How It Works
+
+### Step 1: Request Explicit User Consent
+
+Before executing any command that references local files, repository paths, snippets, command output, secrets-adjacent config, or private project context, you **MUST** obtain explicit user consent to send that material to GitHub Copilot.
+
+Ask for separate approval before allowing Copilot to run tools, execute shell commands, edit files, install packages, or mutate the workspace.
+
+### Step 2: Execute with Minimal Permitted Flags
+
+To prevent TUI lockups, execute the `copilot` command with headless flags. Do not use blanket bypasses such as `--yolo`, `--allow-all-tools`, or `--allow-all-paths` for routine Q&A or review.
+
+- **For Read-Only / General Q&A**: Send only the user-approved, redacted text in the prompt. Do not grant Copilot broad local-path access; it is not needed when the prompt already contains the approved context.
+- **For Trusted Mutation Tasks**: Prefer a scoped permission flag if the CLI supports one. Use blanket mutation bypasses only after the user explicitly authorizes Copilot to execute tools and mutate the workspace for the specific task.
+
+### Step 3: Use Session Management (Optional)
+
+To maintain conversation context, use `--name` and `--resume` flags, or pass a `--session-id` on subsequent calls.
+
+## Examples
+
+### Example 1: General Question (Read-Only)
+
+Does not require repository path access or mutation permissions.
+```bash
+copilot -p "Explain how to implement a debounce function in TypeScript" -s
+```
+
+### Example 2: Code Review (Approved File Excerpt)
+
+Always confirm the exact file and excerpt with the user before executing. Keep the path in a
+quoted variable; build the prompt from a static instruction plus the approved excerpt. Shell
+does not re-evaluate command-substitution output, so metacharacters inside the reviewed file
+remain prompt text rather than shell syntax:
+```bash
+review_file="path/to/file.ts"
+test -f "$review_file" || { echo "File not found: $review_file" >&2; exit 1; }
+copilot -p "$(printf '%s\n\n' 'Review this approved excerpt for potential memory leaks:'; sed -n '1,220p' -- "$review_file")" -s
+```
+
+Never construct a shell command by interpolating user-controlled prompt text, paths, issue
+content, or filenames into shell source. Use fixed command structure, quoted variables, and
+approved file content only.
+
+### Example 3: Named Session Management
+
+```bash
+copilot -p "Remember this session label for follow-up questions." -s --name "my-session-name"
+copilot -p "Summarize the prior advice in this session." -s --resume "my-session-name"
+```
+
+## Best Practices
+
+- ✅ **Do:** Ask for user consent before uploading any project files to third-party endpoints.
+- ✅ **Do:** Send only the approved, redacted excerpt; keep Copilot out of the broader workspace.
+- ✅ **Do:** Keep untrusted values in quoted variables or command input, never in shell source.
+- ✅ **Do:** Use `-s` (silent) to suppress metadata and statistics, leaving only clean output.
+- ❌ **Don't:** Automatically trigger this skill for background second opinions without the user's explicit ask.
+- ❌ **Don't:** Send files, logs, environment details, or private repository context to Copilot without explicit approval.
+- ❌ **Don't:** use `--allow-all-paths` for a review, or interpolate untrusted text inside `copilot -p "..."`.
+- ❌ **Don't:** Run `copilot` without permission-bypass flags in background tasks, as it will hang waiting for interactive input.
+
+## Limitations
+
+- This skill does not replace environment-specific validation, testing, or expert review.
+- Stop and ask for clarification if required inputs, permissions, or safety boundaries are missing.
+- Copilot responses may be incomplete, outdated, or wrong; verify any proposed code locally before using it.
+
+## Security & Safety Notes
+
+- The `--yolo` flag bypasses all permission prompts and allows Copilot CLI to run arbitrary shell commands and mutate workspace files. It must be treated as a high-risk option and never used by default.
+- Always check that the code/files being sent do not contain sensitive credentials, API keys, or private environment variables.
+- Prefer redacted snippets over whole files when only a small context sample is needed.
+- `--allow-all-paths` grants Copilot broader local visibility than a narrow review requires; it is not a read-only least-privilege flag.
+
+## Common Pitfalls
+
+- **Problem:** The terminal hangs or the command times out.
+  **Solution:** Ensure both `-p` (or `--prompt`) and the narrowest required non-interactive permission flag are present in the command arguments. Without required permission flags, the CLI may prompt for confirmation and hang headless processes.
+
+## Related Skills
+
+- `@cli-assistant` - How to interact with CLI tools in general.