AI Agent Skills

When writing custom event handlers for the WhatsApp client, never use await directly on Client methods (such as send_*, mark_read, get_group_info, or download_media) inside the handler function.

Because event handlers run inline on the main receive loop, awaiting a client call will deadlock the connection. Instead, wrap the call in asyncio.create_task(...) to run it concurrently.

Correct Pattern:

# Inside an event handler
asyncio.create_task(client.send_text(jid, "message"))

Jules reads an AGENTS.md file from your repository root to gain context about your project. Creating this file improves the quality of task execution. Include sections for:

• Project Overview: Brief description.
• Tech Stack: Languages, frameworks, and testing tools.
• Code Conventions: Linters, formatters, and naming conventions.
• Testing Requirements: Coverage targets and testing types.
• Build & Deploy: Commands for building and testing.

# AGENTS.md

## Project Overview
[Brief description]

## Tech Stack
- Language: [TypeScript/Python/Go/etc.]
- Framework: [React/FastAPI/Gin/etc.]

## Code Conventions
- [Linter/formatter used]

## Testing Requirements
- Unit tests for new features

## Build & Deploy
- Build: `[command]`
- Test: `[command]`

The PostgreSQL skill is designed as a read-only tool with several built-in protections:

• Read-only sessions: Uses PostgreSQL readonly=True mode to block writes at the database level.
• Query validation: Only SELECT, SHOW, EXPLAIN, and WITH statements are permitted.
• Single statement: Multi-statement queries (e.g., SELECT 1; DROP TABLE) are blocked.
• Timeouts: Queries are capped at 30s and connections at 10s.
• Memory cap: Results are limited to a maximum of 10,000 rows per query.
• Credential protection: Passwords are automatically sanitized from error messages.

You can manage multiple WhatsApp accounts by using the --session flag. This flag must be placed before the subcommand.

Sessions are stored in $PYWHATS_HOME/ as <name>.session and <name>.session.signal.db. If you want to use a specific directory for your sessions, set the PYWHATS_HOME environment variable.

If a session becomes invalid or is logged out, re-run the pair command for that specific session name.

# Pair a specific account named 'work'
scripts/wa.py --session work pair

# Send a message using the 'work' account
scripts/wa.py --session work send-text 15550001234 "hi"

The container ecosystem is driven by the container CLI, which communicates via XPC to a central API server and several specialized helper services.

Crucial Note: No container, image, or build commands will work until you run container system start to launch the control plane.

Component Topology:

• container CLI + ContainerClient: The user entry point.
• container-apiserver: A launchd agent that manages the lifecycle of all helpers. Controlled via container system commands.
• container-core-images: Manages the local content store and image APIs.
• container-network-vmnet: Manages virtual networks via the macOS vmnet framework.
• builder (buildkit): A utility VM that runs container build via gRPC.
• container-runtime-linux: A runtime helper launched per container to manage that specific container's VM.

OAuth tokens for the google-docs skill are stored securely using your operating system's native keyring service under the service name google-docs-skill-oauth.

Supported Keyring Services:

• macOS: Keychain
• Windows: Windows Credential Locker
• Linux: Secret Service API (GNOME Keyring, KDE Wallet, etc.)

Access tokens are automatically refreshed via Google's cloud function when they expire.

The container image command group (aliased to container i) is used to manage the lifecycle of container images.

Available subcommands:

• pull: Download an image from a registry.
• push: Upload an image to a registry.
• tag: Create a new reference for an existing image.
• save: Export images to an OCI-compatible tar archive.
• load: Import images from an OCI tar archive.
• inspect: View detailed image metadata in JSON.
• list / ls: List local images.
• delete / rm: Remove images.
• prune: Remove unused images.

container i <subcommand>

The MSSQL skill is designed for safe, read-only data exploration. It includes several enforcement mechanisms:

• Read-only enforcement: Only SELECT, SHOW, EXPLAIN, WITH, and SP_HELP queries are allowed. All write operations (e.g., INSERT, UPDATE, DELETE, DROP) are blocked.
• Single statement: Only one SQL statement is allowed per query execution.
• Timeouts: A 30-second query timeout and a 10-second connection timeout are enforced.
• Memory protection: To prevent Out-of-Memory (OOM) errors, the skill limits results to a maximum of 10,000 rows per query.
• Output constraints: Column width is capped at 100 characters for readability.
• Credential security: Error messages are sanitized to prevent leaking passwords.

When performing operations on a document, you can identify it in three ways:

1. Document ID: The unique string found in the URL (e.g., 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms).
2. Full URL: The complete browser address (e.g., https://docs.google.com/document/d/.../edit). The CLI will automatically extract the ID from the URL.
3. Search Results: Use the find command to retrieve IDs for existing documents.

Unlike Docker or Podman, which use a single long-lived Linux VM to host multiple containers via kernel namespaces, container uses a one-VM-per-container design. Each container runs inside its own dedicated, lightweight Linux VM booting a minimal Linux kernel and vminitd init.

Key Implications:

• Security: Provides full VM isolation for every container, reducing the attack surface compared to shared-kernel namespace isolation.
• Privacy: You mount only the specific host data required for a specific container into its VM, avoiding the broad exposure required by shared-VM models.
• Performance: Offers sub-second boot times and lower memory overhead than a full-sized VM.
• Compatibility: Uses standard OCI images, meaning images can be moved freely between container and other OCI-compliant tools like Docker.

container run <image>