@marcfargas/skills 0.2.0 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Marc
+Copyright (c) 2026 Marc Fargas
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/LICENSE-CC0

@@ -0,0 +1,118 @@
+CC0 1.0 Universal
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator and
+subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for the
+purpose of contributing to a commons of creative, cultural and scientific
+works ("Commons") that the public can reliably and without fear of later
+claims of infringement build upon, modify, incorporate in other works, reuse
+and redistribute as freely as possible in any form whatsoever and for any
+purposes, including without limitation commercial purposes. These owners may
+contribute to the Commons to promote the ideal of a free culture and the
+further production of creative, cultural and scientific works, or to gain
+reputation or greater distribution for their Work in part through the use and
+efforts of others.
+
+For these and/or other purposes and motivations, and without any expectation
+of additional consideration or compensation, the person associating CC0 with a
+Work (the "Affirmer"), to the extent that he or she is an owner of Copyright
+and Related Rights in the Work, voluntarily elects to apply CC0 to the Work
+and publicly distribute the Work under its terms, with knowledge of his or her
+Copyright and Related Rights in the Work and the meaning and intended legal
+effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not limited
+to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display, communicate,
+     and translate a Work;
+
+ ii. moral rights retained by the original author(s) and/or performer(s);
+
+iii. publicity and privacy rights pertaining to a person's image or likeness
+     depicted in a Work;
+
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+
+  v. rights protecting the extraction, dissemination, use and reuse of data in
+     a Work;
+
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation thereof,
+     including any amended or successor version of such directive); and
+
+vii. other similar, equivalent or corresponding rights throughout the world
+     based on applicable law or treaty, and any national implementations
+     thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention of,
+applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and
+unconditionally waives, abandons, and surrenders all of Affirmer's Copyright
+and Related Rights and associated claims and causes of action, whether now
+known or unknown (including existing as well as future claims and causes of
+action), in the Work (i) in all territories worldwide, (ii) for the maximum
+duration provided by applicable law or treaty (including future time
+extensions), (iii) in any current or future medium and for any number of
+copies, and (iv) for any purpose whatsoever, including without limitation
+commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes
+the Waiver for the benefit of each member of the public at large and to the
+detriment of Affirmer's heirs and successors, fully intending that such Waiver
+shall not be subject to revocation, rescission, cancellation, termination, or
+any other legal or equitable action to disrupt the quiet enjoyment of the Work
+by the public as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason be
+judged legally invalid or ineffective under applicable law, then the Waiver
+shall be preserved to the maximum extent permitted taking into account
+Affirmer's express Statement of Purpose. In addition, to the extent the Waiver
+is so judged Affirmer hereby grants to each affected person a royalty-free,
+non transferable, non sublicensable, non exclusive, irrevocable and
+unconditional license to exercise Affirmer's Copyright and Related Rights in
+the Work (i) in all territories worldwide, (ii) for the maximum duration
+provided by applicable law or treaty (including future time extensions), (iii)
+in any current or future medium and for any number of copies, and (iv) for any
+purpose whatsoever, including without limitation commercial, advertising or
+promotional purposes (the "License"). The License shall be deemed effective as
+of the date CC0 was applied by Affirmer to the Work. Should any part of the
+License for any reason be judged legally invalid or ineffective under
+applicable law, such partial invalidity or ineffectiveness shall not invalidate
+the remainder of the License, and in such case Affirmer hereby affirms that he
+or she will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of action
+with respect to the Work, in either case contrary to Affirmer's express
+Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+
+ b. Affirmer offers the Work as-is and makes no representations or warranties
+    of any kind concerning the Work, express, implied, statutory or otherwise,
+    including without limitation warranties of title, merchantability, fitness
+    for a particular purpose, non infringement, or the absence of latent or
+    other defects, accuracy, or the present or absence of errors, whether or
+    not discoverable, all to the greatest extent permissible under applicable
+    law.
+
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without limitation
+    any person's Copyright and Related Rights in the Work. Further, Affirmer
+    disclaims responsibility for obtaining any necessary consents, permissions
+    or other rights required for any use of the Work.
+
+ d. Affirmer understands and acknowledges that Creative Commons is not a party
+    to this document and has no duty or obligation with respect to this CC0 or
+    use of the Work.
+
+For more information, please see
+<http://creativecommons.org/publicdomain/zero/1.0/>

package/README.md

@@ -7,7 +7,9 @@ Reusable skills for AI coding agents. Works with [pi](https://github.com/marioze
 | Category | Skill | Description |
 |----------|-------|-------------|
 | ☁️ Google Cloud | [gcloud](google-cloud/gcloud/) | GCP CLI with agent safety model — hub + 7 reference files |
+| ⚙️ Process | [pm2](process/pm2/) | Process management — keep services alive, auto-restart, monitoring, ecosystem configs |
 | 🚀 Release | [pre-release](release/pre-release/) | Pre-release checklist + AI-written changesets via @changesets/cli |
+| 🔍 Search | [web-search](search/web-search/) | Web search + content extraction via [ddgs](https://github.com/deedy5/ddgs) — no API keys |
 | 🎬 Terminal | [vhs](terminal/vhs/) | Record terminal sessions as GIF/MP4 with [VHS](https://github.com/charmbracelet/vhs) |
 
 ## Install
@@ -42,13 +44,26 @@ Copy the skill directory into your agent's skill folder:
 cp -r google-cloud/gcloud ~/.claude/skills/gcloud
 ```
 
-## Skill Design Principles
+## How We Build Skills
 
-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
+### Multi-Model Review
+
+Every skill is reviewed by **3+ models** (Claude, Gemini, GPT) before publishing — structure, agent usability, safety, and real-world scenario testing. If an agent can misinterpret an instruction, we find out before you do.
+
+### Safety Classification
+
+Every operation is classified: **READ** / **WRITE** / **DESTRUCTIVE** / **EXPENSIVE** / **FORBIDDEN**. Destructive and expensive operations are gated — the agent must confirm before executing, and costs are flagged upfront.
+
+### Progressive Discovery
+
+Skills use a **hub + spoke** architecture. The SKILL.md hub is ~140 lines — just enough to match the right skill and know what's available. Detailed per-topic reference files are loaded on demand, keeping your context window lean.
+
+### Also
+
+- **Agent-native** — `--format=json` everywhere, idempotent patterns, structured error handling
+- **Portable** — no hardcoded paths, no personal config, works on any machine
+- **Spec-compliant** — validated against the [Agent Skills specification](https://agentskills.io/specification) using [skills-ref](https://github.com/agentskills/agentskills) in CI
+- **Continuous validation** — `agentskills validate` on every push ([validate.yml](.github/workflows/validate.yml)), [pre-release checklist](release/pre-release/) with AI-written changesets, [npm Trusted Publishing](https://docs.npmjs.com/trusted-publishers) with provenance
 
 ## Structure
 
@@ -56,21 +71,26 @@ cp -r google-cloud/gcloud ~/.claude/skills/gcloud
 skills/
 ├── google-cloud/
 │   └── gcloud/          # 8 files, ~1100 lines total
+├── process/
+│   └── pm2/             # 1 file
 ├── release/
 │   └── pre-release/     # 1 file
+├── search/
+│   └── web-search/      # SKILL.md + search.js + content.js
 ├── terminal/
 │   └── vhs/             # 1 file
 └── README.md
 ```
 
-## External Skills (planned)
+## External Skills
 
-Some skills are developed in their own repositories and synced here:
+Some skills live in their own repositories — install them directly or via their npm packages:
 
-| Skill | Source Repo | Status |
-|-------|-------------|--------|
-| odoo | `odoo-toolbox` | Planned |
-| go-easy | `go-easy` | Planned |
+| Skill | Description | Install |
+|-------|-------------|---------|
+| [go-easy](https://github.com/marcfargas/go-easy) | Gmail, Drive, Calendar for AI agents — `npx go-gmail`, `npx go-drive`, `npx go-calendar` | `npx skills add marcfargas/go-easy` |
+| [holdpty](https://github.com/marcfargas/holdpty) | Detached PTY sessions — launch, attach, view, record terminal processes | `npx skills add marcfargas/holdpty` |
+| [odoo](https://github.com/marcfargas/odoo-toolbox) | Odoo ERP integration — connect, introspect, automate | `npx skills add marcfargas/odoo-toolbox` |
 
 ## Contributing
 
@@ -101,6 +121,16 @@ 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).
 
+## Sponsor
+
+Building high-quality, multi-model-reviewed agent skills takes serious token budget. If these skills save you time, consider sponsoring:
+
+[![GitHub Sponsors](https://img.shields.io/github/sponsors/marcfargas?style=for-the-badge&logo=github&label=Sponsor)](https://github.com/sponsors/marcfargas)
+
 ## License
 
-MIT
+**Code** (scripts, tooling): [MIT](./LICENSE)
+
+**Skill content** (`**/SKILL.md` and reference docs): [CC0 1.0 Universal](./LICENSE-CC0) — public domain, no attribution required.
+
+Why CC0 for skills: Skill docs are consumed by AI agents and freely incorporated into any workflow. Attribution requirements create friction in agent contexts where provenance tracking is impractical.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcfargas/skills",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Reusable AI agent skills for pi, Claude Code, Cursor, and any Agent Skills compatible agent",
   "license": "MIT",
   "author": "Marc Fargas <marc@marcfargas.com>",
@@ -14,12 +14,17 @@
     "ai-agent",
     "skills",
     "gcloud",
-    "vhs"
+    "pm2",
+    "pre-release",
+    "vhs",
+    "web-search"
   ],
   "pi": {
     "skills": [
       "google-cloud",
+      "process",
       "release",
+      "search",
       "terminal"
     ]
   },
@@ -34,9 +39,12 @@
   },
   "files": [
     "google-cloud/",
+    "process/",
     "release/",
+    "search/",
     "terminal/",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "LICENSE-CC0"
   ]
 }

package/process/pm2/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: pm2
+description: >-
+  Process management with PM2 — start, stop, restart, monitor long-running
+  processes. Use when: keeping services alive, auto-restart on crash, managing
+  daemon processes, ecosystem configs, log management, startup scripts, process
+  monitoring. Triggers: pm2, process manager, keep alive, daemon, auto-restart,
+  ecosystem config, process monitoring.
+---
+
+# PM2 — Process Manager
+
+PM2 keeps processes alive, restarts them on crash, and provides monitoring/logging.
+Use for long-running services, persistent agents, background workers.
+
+> **Not for detached terminals** — use [holdpty](https://github.com/marcfargas/holdpty) when you need PTY output, attach/view, or interactive sessions.
+> **Not for ephemeral tasks** — use `pi -p > file &` for quick fire-and-forget agent runs.
+
+## Quick Reference
+
+### Start a process
+
+```bash
+# Simple
+pm2 start server.js --name myapp
+
+# With interpreter
+pm2 start script.py --interpreter python3 --name worker
+
+# With arguments (use -- to separate pm2 args from script args)
+pm2 start app.js --name api -- --port 3000 --env production
+
+# From ecosystem file
+pm2 start ecosystem.config.cjs
+```
+
+### Manage processes
+
+```bash
+pm2 list                    # List all processes (table)
+pm2 jlist                   # List as JSON (for scripting)
+pm2 info <name|id>          # Detailed process info
+pm2 restart <name|id|all>   # Restart
+pm2 stop <name|id|all>      # Stop (keeps in list)
+pm2 delete <name|id|all>    # Stop + remove from list
+pm2 restart <name> --update-env  # Restart with refreshed env vars
+```
+
+### Logs
+
+```bash
+pm2 logs                     # Tail all logs
+pm2 logs <name> --lines 50   # Tail specific process, last 50 lines
+pm2 flush                    # Clear all log files
+```
+
+Log files location: `~/.pm2/logs/<name>-out.log` and `<name>-error.log`.
+
+### Monitoring
+
+```bash
+pm2 monit          # Real-time TUI: CPU, memory, logs
+pm2 dash           # Dashboard with monitoring + logs
+```
+
+## Ecosystem Config
+
+For reproducible multi-process setups, use an `ecosystem.config.cjs` file:
+
+```javascript
+// ecosystem.config.cjs
+module.exports = {
+  apps: [
+    {
+      name: "api",
+      script: "dist/server.js",
+      instances: 2,                // cluster mode
+      exec_mode: "cluster",
+      env: {
+        NODE_ENV: "production",
+        PORT: 3000,
+      },
+      max_memory_restart: "500M",
+      log_date_format: "YYYY-MM-DD HH:mm:ss",
+    },
+    {
+      name: "worker",
+      script: "dist/worker.js",
+      autorestart: true,
+      max_restarts: 10,
+      restart_delay: 5000,
+      exp_backoff_restart_delay: 100,  // exponential backoff
+      watch: false,
+    },
+  ],
+};
+```
+
+```bash
+pm2 start ecosystem.config.cjs           # Start all apps
+pm2 start ecosystem.config.cjs --only api  # Start specific app
+pm2 restart ecosystem.config.cjs          # Restart all
+pm2 delete ecosystem.config.cjs           # Stop + remove all
+```
+
+### Useful ecosystem options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `script` | string | Script to run (required) |
+| `interpreter` | string | Override interpreter (default: `node`) |
+| `args` | string or string[] | Script arguments |
+| `cwd` | string | Working directory |
+| `instances` | number | Number of instances (cluster mode) |
+| `exec_mode` | string | `"fork"` (default) or `"cluster"` |
+| `autorestart` | boolean | Auto-restart on exit (default: `true`) |
+| `max_restarts` | number | Max consecutive restarts before stopping |
+| `restart_delay` | number | Delay between restarts (ms) |
+| `exp_backoff_restart_delay` | number | Exponential backoff base (ms) |
+| `max_memory_restart` | string | Restart if memory exceeds (e.g. `"500M"`) |
+| `cron_restart` | string | Cron-based restart schedule |
+| `watch` | boolean or string[] | Watch for file changes |
+| `ignore_watch` | string[] | Paths to ignore when watching |
+| `env` | object | Environment variables |
+| `log_date_format` | string | Timestamp format for logs |
+| `error_file` | string | Custom stderr log path |
+| `out_file` | string | Custom stdout log path |
+| `merge_logs` | boolean | Merge cluster instance logs |
+| `stop_exit_codes` | number[] | Exit codes that skip auto-restart |
+
+## Persistence
+
+```bash
+pm2 save               # Save current process list
+pm2 resurrect           # Restore saved process list
+pm2 startup             # Generate OS startup script (auto-start on boot)
+pm2 unstartup           # Remove startup script
+```
+
+After `pm2 startup`, run the command it outputs (may need admin/sudo).
+Then `pm2 save` to snapshot current processes — they'll auto-start on reboot.
+
+## Windows Gotchas
+
+### `.cmd` wrapper resolution
+
+PM2 tries to run `.cmd` files as Node.js scripts. **Never start a `.cmd` shim directly** with PM2.
+
+```bash
+# ❌ WRONG — resolves to pi.cmd, crashes
+pm2 start pi -- -p "prompt"
+
+# ✅ CORRECT — point to the actual .js entry point
+pm2 start /path/to/cli.js --interpreter node -- -p "prompt"
+```
+
+For npm-installed CLIs, find the real script:
+
+```bash
+# Find where the .cmd shim points
+cat "$(which pi)" | head -5
+# → Look for the .js path, then use that with --interpreter node
+```
+
+In ecosystem configs, always use the resolved `.js` path:
+
+```javascript
+module.exports = {
+  apps: [{
+    name: "my-agent",
+    // Resolve the actual cli.js, not the .cmd wrapper
+    script: "C:\\path\\to\\node_modules\\package\\dist\\cli.js",
+    interpreter: "node",
+    args: ["--mode", "json"],
+  }],
+};
+```
+
+### Log paths
+
+PM2 stores logs at `~/.pm2/logs/`. On Windows this is typically `C:\Users\<user>\.pm2\logs\`.
+
+### Daemon
+
+PM2 daemon runs as a background Node.js process. `pm2 kill` stops the daemon and all managed processes. `pm2 ping` checks if the daemon is running.
+
+## Agent Patterns
+
+### Launch a pi agent as a persistent service
+
+First, find the actual `cli.js` path (see Windows Gotchas above):
+
+```bash
+# Find pi's real entry point
+cat "$(which pi)" | head -5
+# e.g. → /path/to/node_modules/@mariozechner/pi-coding-agent/dist/cli.js
+```
+
+```javascript
+// ecosystem.config.cjs
+module.exports = {
+  apps: [{
+    name: "my-agent",
+    // Use the resolved cli.js path — NOT the .cmd wrapper
+    script: "/path/to/node_modules/@mariozechner/pi-coding-agent/dist/cli.js",
+    interpreter: "node",
+    args: ["--mode", "json", "--cwd", "/path/to/project"],
+    autorestart: true,
+    max_restarts: 10,
+    restart_delay: 5000,
+  }],
+};
+```
+
+> **Note**: `pi -p` to non-TTY only outputs final text. Use `--mode json` for full event streaming to PM2 logs.
+
+### Check process health from an agent
+
+```bash
+# Structured output for parsing
+pm2 jlist | node -e "
+  const d = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
+  d.forEach(p => console.log(p.name, p.pm2_env.status, 'restarts:', p.pm2_env.restart_time));
+"
+```
+
+### Rotate logs
+
+```bash
+pm2 install pm2-logrotate        # Install log rotation module
+pm2 set pm2-logrotate:max_size 10M
+pm2 set pm2-logrotate:retain 5
+```
+
+## When NOT to Use PM2
+
+- **Detached terminal sessions** → use [holdpty](https://github.com/marcfargas/holdpty) (PTY output, attach/view)
+- **Ephemeral agent runs** → use `pi -p > file &` (fire-and-forget with output capture)
+- **Containers** → the container runtime manages lifecycle; PM2 inside Docker is usually redundant
+- **Systemd environments** → use systemd service units natively on Linux

package/search/web-search/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: web-search
+description: >-
+  Web search and content extraction using ddgs (multi-engine metasearch). No API keys required.
+  Use when: searching documentation, facts, current information, news, fetching web content.
+  Triggers: search the web, look up, find information, web search, news search, fetch page.
+---
+
+# Web Search
+
+Web search and content extraction using [ddgs](https://github.com/deedy5/ddgs) — a multi-engine metasearch CLI.
+No API keys, no signup, no browser required.
+
+## Setup
+
+Install ddgs (run once):
+
+```bash
+uv tool install ddgs
+```
+
+Install Node.js dependencies for content extraction (run once):
+
+```bash
+cd {baseDir}
+npm install
+```
+
+## Search
+
+```bash
+{baseDir}/search.js "query"                         # Basic search (5 results)
+{baseDir}/search.js "query" -n 10                   # More results
+{baseDir}/search.js "query" --content               # Include page content as markdown
+{baseDir}/search.js "query" -t w                    # Results from last week
+{baseDir}/search.js "query" -t m                    # Results from last month
+{baseDir}/search.js "query" -r es-es                # Results in Spanish
+{baseDir}/search.js "query" -b google               # Use Google backend
+{baseDir}/search.js "query" -n 3 --content          # Combined options
+```
+
+### Options
+
+- `-n <num>` — Number of results (default: 5)
+- `--content` — Fetch and include page content as markdown
+- `-r <region>` — Region code: `us-en`, `es-es`, `de-de`, `fr-fr`, etc. (default: none)
+- `-t <timelimit>` — Filter by time: `d` (day), `w` (week), `m` (month), `y` (year)
+- `-b <backend>` — Search backend: `auto`, `all`, `bing`, `brave`, `duckduckgo`, `google`, `mojeek`, `yandex`, `yahoo`, `wikipedia` (default: auto)
+
+## News Search
+
+```bash
+{baseDir}/search.js --news "query"                  # News search
+{baseDir}/search.js --news "query" -n 10 -t w       # News from last week
+{baseDir}/search.js --news "query" --content         # News with full article content
+```
+
+News backends: `auto`, `all`, `bing`, `duckduckgo`, `yahoo`
+
+## Extract Page Content
+
+```bash
+{baseDir}/content.js https://example.com/article
+```
+
+Fetches a URL and extracts readable content as markdown.
+
+## Output Format
+
+### Text search
+
+```
+--- Result 1 ---
+Title: Page Title
+Link: https://example.com/page
+Snippet: Description from search results
+Content: (if --content flag used)
+  Markdown content extracted from the page...
+
+--- Result 2 ---
+...
+```
+
+### News search
+
+```
+--- Result 1 ---
+Title: Article Title
+Link: https://news.example.com/article
+Date: 2026-02-08T10:18:00+00:00
+Source: Reuters
+Snippet: Article summary...
+Content: (if --content flag used)
+  Full article as markdown...
+
+--- Result 2 ---
+...
+```
+
+## When to Use
+
+- Searching for documentation or API references
+- Looking up facts or current information
+- News search for recent events
+- Fetching content from specific URLs
+- Any task requiring web search without interactive browsing
+- When no API key is available (unlike Brave Search)