---
name: astro
description: 'The sky over a place and date -- moon phase, sunrise and sunset -- computed, not fetched. Tools: daylight, moon-phase, sun-times. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: 'Requires fragletc and Docker. Hermetic: no network access.'
metadata:
  tags: world
  tools: daylight.py, moon-phase.py, sun-times.py
---

# Astro

The sky over a place and date -- moon phase, sunrise and sunset -- computed, not fetched.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/daylight.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `daylight.py`

How light it is outside right now at a latitude and longitude, as one number from 0 (night) to 1 (the sun overhead): the sine of the sun's altitude, computed with ephem (no network). A body can grow by it.

Use when an agent's body or a card wants daylight now as a single number, e.g. a plant that opens in the sun.

```sh
<skill-dir>/daylight.py -p lat="<lat>" -p lon="<lon>" --output light.txt
```

Parameters:
- `lat` (string, required) — Latitude in decimal degrees, e.g. 43.65
- `lon` (string, required) — Longitude in decimal degrees, east positive, e.g. -79.38

Outputs:
- `light.txt` — copy out with `--output light.txt[=<host path>]`

Runs in `ofthemachine/python3@sha256:59784cff1945b7d6093a591b5e5292b8c989f0691af0494fbbe1c6b8083a16cb`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `moon-phase.py`

The Moon's phase on a given UTC date, computed with ephem (no network): phase name, percent illuminated, and the dates of the next new and full moon. One line, ready for a dateline or an almanac box. The date is a parameter, never the clock, so the same inputs always give the same answer.

Use when the user asks what phase the moon is in or when the next full or new moon is, or an almanac, dateline, or caption needs the moon for a specific date.

```sh
<skill-dir>/moon-phase.py -p date="<date>"
```

Parameters:
- `date` (string, required) — UTC date as YYYY-MM-DD

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `sun-times.py`

Sunrise, sunset, and day length for a latitude, longitude, and UTC date, computed with ephem (no network). Times are printed in the given UTC offset so a caller can pass the local zone; the day-length delta against the day before says whether days are getting longer or shorter. Companion to net/ip-location.py, whose lat,lon this takes.

Use when the user asks when the sun rises or sets somewhere, how long the day is, or an almanac or weather box needs sun times for a place and date.

```sh
<skill-dir>/sun-times.py -p lat="<lat>" -p lon="<lon>" -p date="<date>" [-p utc_offset=0]
```

Parameters:
- `lat` (string, required) — Latitude in decimal degrees, e.g. 53.5457
- `lon` (string, required) — Longitude in decimal degrees, east positive, e.g. -113.5
- `date` (string, required) — UTC date as YYYY-MM-DD
- `utc_offset` (string, optional, default `0`) — Hours to add when printing times, e.g. -6 for Edmonton in September

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.


---
name: catalog
description: 'Build, check, publish, and depend on a catalog of fraglet tools -- compile packs into skills, validate the result, render its website, and vendor pinned tools into another repository. Tools: compile, site, validate, vendor. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: Requires fragletc and Docker. Network access required.
metadata:
  tags: engineering, internet
  tools: compile.py, site.py, validate.py, vendor.py
---

# Catalog

Build, check, publish, and depend on a catalog of fraglet tools -- compile packs into skills, validate the result, render its website, and vendor pinned tools into another repository.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/compile.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `compile.py`

Compile a catalog of level-0 tools -- a tarball of pack directories, each an index.md plus fraglet files -- into its projections: one Agent Skill per pack (SKILL.md beside byte-identical copies of the tools), a Claude Code plugin per pack with a marketplace.json, llms.txt and llms-full.txt for agents arriving over HTTP, manifest.json with every tool's contract and procedure_hash, and an Open Knowledge Format bundle. Everything is derived from the tools' own headers and the pack index files; nothing is authored twice.

Use when the user asks to build, rebuild, or regenerate the tools catalog, or wants the skills, llms.txt, marketplace, or OKF views of a set of fraglet tools.

```sh
<skill-dir>/compile.py -p archive="<archive>" [-p host=tools.ofthemachine.com] --output tools.tar.gz
```

Parameters:
- `archive` (file, required) — tar/tar.gz of the catalog source: index.md at the top level (optionally CONTRIBUTING.md beside it, copied through verbatim) plus one directory per pack (<pack>/index.md and the pack's tool files)
- `host` (string, optional, default `tools.ofthemachine.com`) — Canonical host (served over https) where the catalog is published; OKF concepts locate computations by URL there, paired with procedure_hash

Outputs:
- `tools.tar.gz` — copy out with `--output tools.tar.gz[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `site.py`

Render a compiled tools catalog (archived) into a static website: the catalog itself served verbatim -- llms.txt, manifest.json, every pack's SKILL.md and every tool file at the same paths -- plus an HTML layer over it: an explorer of every tool with search, tag and pack filters, grid and table views and a dark/light theme; one page per pack; one page per tool with its contract, provenance, a curl one-liner and its full source. Relative links throughout, so the result works from a file:// URL as well as a web root.

Use when the user wants the browsable website for a tools catalog, or CI publishes tools.ofthemachine.com from a freshly built catalog.

```sh
<skill-dir>/site.py -p archive="<archive>" [-p host=tools.ofthemachine.com] --output site.tar.gz
```

Parameters:
- `archive` (file, required) — tools.tar.gz as catalog/compile.py emits it (the site root is the catalog root)
- `host` (string, optional, default `tools.ofthemachine.com`) — Canonical host (served over https), used in curl one-liners, canonical links, and the CNAME file

Outputs:
- `site.tar.gz` — copy out with `--output site.tar.gz[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `validate.py`

Validate a compiled tools catalog (archived): every pack's SKILL.md against the agentskills.io specification using skills-ref, the spec's own reference validator; every tool file present, executable, and hashing to the procedure_hash manifest.json records for it; every llms.txt link resolving; marketplace.json plugins matching the pack directories; and, if an okf/ bundle is present, every concept typed and every relative link resolving. Prints one line per finding and a summary; exit 0 only when clean.

Use when the user asks whether a compiled catalog of packs is valid, as the catalog build's validation step, or before publishing a catalog.

```sh
<skill-dir>/validate.py -p archive="<archive>" [-p strict=true]
```

Parameters:
- `archive` (file, required) — tar/tar.gz/zip of a compiled catalog: <pack>/SKILL.md and tools, manifest.json, llms.txt, marketplace.json, optional okf/
- `strict` (string, optional, default `true`) — Treat warnings (body over 500 lines) as failures when true

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `vendor.py`

Fetch the catalog tools a project depends on, verify each against its pinned procedure_hash, and pack them into vendor.tar.gz (executable, at their catalog paths, reproducible bytes). The lock file names where the tools are published ("source https://tools.ofthemachine.com") and lists one "<pack>/<stem>.<ext> sha256:<hex>" per line (# comments allowed); the hashes are what manifest.json and every receipt call procedure_hash. A file whose hash does not match is refused and nothing is written, so base_url may fetch from anywhere -- a mirror, or a local `make serve` -- without weakening the pin or changing the recorded source.

Use when bootstrapping a repository that runs catalog tools from its own Makefile or CI: turn its tools.lock into a verified vendor/ directory before running anything.

```sh
<skill-dir>/vendor.py -p lock="<lock>" [-p base_url="<base_url>"] --output vendor.tar.gz
```

Parameters:
- `lock` (file, required) — tools.lock: a "source <url>" line, then "<pack>/<stem>.<ext> sha256:<hex>" per line
- `base_url` (string, optional) — Fetch from here instead of the lock's source (a mirror, or http://host.docker.internal:8080); integrity comes from the hashes, not the host

Outputs:
- `vendor.tar.gz` — copy out with `--output vendor.tar.gz[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.


---
name: chart
description: 'Generate standalone SVG vector charts (bar, line, scatter, pie) from tabular data. Tools: plot. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: 'Requires fragletc and Docker. Hermetic: no network access.'
metadata:
  tags: media, computation
  tools: plot.py
---

# Chart

Generate standalone SVG vector charts (bar, line, scatter, pie) from tabular data.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/plot.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `plot.py`

Generate standalone SVG vector charts (bar, line, scatter, pie) from CSV or JSON data.

Use when the user wants to visualize data, plot metrics, create a chart, or generate an SVG graph from numbers.

```sh
<skill-dir>/plot.py [-p data="<data>"] [-p data_text="<data_text>"] [-p type=bar] [-p title=] [-p x="<x>"] [-p y="<y>"] [-p width=800] [-p height=500] --output chart.svg
```

Parameters:
- `data` (file, optional) — CSV or JSON data file mounted at /input/data
- `data_text` (string, optional) — Inline CSV or JSON text (or pipe stdin)
- `type` (string, optional, default `bar`) — Chart type: bar, line, scatter, pie
- `title` (string, optional, default ``) — Chart title displayed at the top
- `x` (string, optional) — Field name or 1-indexed column for X axis / labels
- `y` (string, optional) — Field name or 1-indexed column for Y axis / values
- `width` (string, optional, default `800`) — SVG viewport width in pixels
- `height` (string, optional, default `500`) — SVG viewport height in pixels
- stdin (optional) — piped input is read in full and hashed into the run's receipt

Outputs:
- `chart.svg` — copy out with `--output chart.svg[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.


---
name: cloudflare
description: 'What a Cloudflare account is using, read with a read-only API token -- today''s Worker requests against the daily quota, and where they come from; its traffic over 24 minutes, hours and days, charted and diagnosed. Tools: latency, traffic, usage. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: Requires fragletc and Docker. Network access required.
metadata:
  tags: engineering, internet
  tools: latency.py, traffic.py, usage.py
---

# Cloudflare

What a Cloudflare account is using, read with a read-only API token -- today's Worker requests against the daily quota, and where they come from; its traffic over 24 minutes, hours and days, charted and diagnosed.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/latency.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `latency.py`

How fast a Cloudflare site's origin answers, path by path: requests, p50/p95/p99 and size over the last 24 hours, against the last hour and the 24 hours before, flagging a real slowdown. An address making most of a window's requests is left out of it and named, so a flood cannot skew the numbers. Long polls are labelled and never flagged: their time is waiting. Read-only.

Use when someone asks how fast a Cloudflare site is answering, which path is slow, or whether a change made it faster or slower; for how much traffic and from whom, use cloudflare/traffic.

```sh
<skill-dir>/latency.py -p zone="<zone>" [-p longpoll=] [-p top=12] --output report.md
```

Parameters:
- `zone` (string, required) — The zone (domain) to read, e.g. example.com
- `longpoll` (string, optional, default ``) — Comma-separated paths that wait for news by design, e.g. /v1/since
- `top` (string, optional, default `12`) — How many paths to list
- `CLOUDFLARE_API_TOKEN` (secret, required) — read from the caller's environment, never passed with `-p`; A Cloudflare API token with Zone Analytics read and Zone read (read-only)

Outputs:
- `report.md` — copy out with `--output report.md[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `traffic.py`

A Cloudflare zone's traffic over the last 24 minutes, 24 hours and 24 days, drawn and diagnosed: traffic.svg stacks the three as small multiples (requests from clients by status class, the daily Worker quota and today's projection on the days), worker.svg is the Worker's CPU time per hour against the free plan's 10 ms limit, and report.md is a Markdown report (a headline, the golden signals against the 24 hours before, the top talkers by kind of client and path, and diagnostics that name a poller, the side a 5xx came from, CPU headroom and the quota's pace). Clients are counted by kind (a browser by name, else a program). Read-only; cloudflare/usage is the quota alone, as gauges. It names the top client addresses, with country and client.

Use when someone asks what traffic a Cloudflare site or Worker is getting, for a chart of its requests over minutes, hours or days, why it returns errors, who is driving its request count, or how close it is to the daily Workers quota.

```sh
<skill-dir>/traffic.py -p zone="<zone>" [-p quota=100000] [-p tz=UTC] [-p top=5] --output traffic.svg
```

Parameters:
- `zone` (string, required) — The zone (domain) to read, e.g. example.com
- `quota` (string, optional, default `100000`) — Worker requests a day the plan allows (the free plan: 100000)
- `tz` (string, optional, default `UTC`) — The IANA time zone the charts' times are shown in (the quota's day is always UTC's)
- `top` (string, optional, default `5`) — How many top talkers and top addresses to list
- `CLOUDFLARE_API_TOKEN` (secret, required) — read from the caller's environment, never passed with `-p`; A Cloudflare API token with Account Analytics read and Zone read (read-only)

Outputs:
- `traffic.svg` — copy out with `--output traffic.svg[=<host path>]`
- `worker.svg` — copy out with `--output worker.svg[=<host path>]`
- `report.md` — copy out with `--output report.md[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `usage.py`

A zone's Worker requests today (the UTC day Cloudflare's daily quota counts) against that quota: how many so far, where the day ends if the last hour's rate holds, and the share of the quota that is, by Worker script; then the last hour's requests to the zone by path and by kind of client (a browser by name, else a program), never by address. The gauges are files (used.txt, projected.txt, share.txt, the projected share as a fraction) and stdout is a short report. Read-only: the token needs only Analytics read and Zone read.

Use when someone asks how close a Cloudflare Workers site is to its daily request limit, what is driving its request count, or whether a client is polling too hard.

```sh
<skill-dir>/usage.py -p zone="<zone>" [-p quota=100000] [-p top=8] --output used.txt
```

Parameters:
- `zone` (string, required) — The zone (domain) whose Workers to read, e.g. example.com
- `quota` (string, optional, default `100000`) — Worker requests a day the plan allows (the free plan: 100000)
- `top` (string, optional, default `8`) — How many paths and clients to list
- `CLOUDFLARE_API_TOKEN` (secret, required) — read from the caller's environment, never passed with `-p`; A Cloudflare API token with Account Analytics read and Zone read (read-only)

Outputs:
- `used.txt` — copy out with `--output used.txt[=<host path>]`
- `projected.txt` — copy out with `--output projected.txt[=<host path>]`
- `share.txt` — copy out with `--output share.txt[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.


---
name: code
description: 'Source-code structure and analysis -- symbol outlines across 140+ languages. Tools: symbol-outline. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: 'Requires fragletc and Docker. Hermetic: no network access.'
metadata:
  tags: engineering
  tools: symbol-outline.py
---

# Code

Source-code structure and analysis -- symbol outlines across 140+ languages.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/symbol-outline.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `symbol-outline.py`

Extract compact hierarchical polyglot symbol outlines (classes, interfaces, functions, methods, structs) from source code across 140+ languages using Universal Ctags, omitting implementation bodies for up to 95% token savings.

Use when the user wants the structure of a source file or codebase (classes, functions, signatures) without reading whole files, or before planning edits across large files.

```sh
<skill-dir>/symbol-outline.py -p code_source="<code_source>" [-p file_path="<file_path>"] [-p file_ext="<file_ext>"] [-p language="<language>"]
```

Parameters:
- `code_source` (file, required) — Source file mounted at /input/code_source
- `file_path` (string, optional) — Original host path, used only for its extension (e.g. pkg/x.go)
- `file_ext` (string, optional) — Explicit extension override (py, .go, rs)
- `language` (string, optional) — ctags language name for --language-force, or a short extension

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.


---
name: data
description: 'Slice, filter, and reshape structured data with jq and SQL. Tools: jq, sql. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: 'Requires fragletc and Docker. Hermetic: no network access.'
metadata:
  tags: engineering, computation
  tools: jq.py, sql.py
---

# Data

Slice, filter, and reshape structured data with jq and SQL.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/jq.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `jq.py`

Slice, transform, filter, and extract JSON data using jq query expressions on JSON text or JSON files.

Use when the user wants to filter, reshape, or pull fields out of JSON, or an API payload needs trimming before it enters context.

```sh
<skill-dir>/jq.py -p filter="<filter>" [-p json_source="<json_source>"] [-p json_text="<json_text>"]
```

Parameters:
- `filter` (string, required) — jq filter expression, e.g. .items[].name
- `json_source` (file, optional) — Host JSON file mounted at /input/json_source
- `json_text` (string, optional) — Inline JSON text (or pipe stdin)
- stdin (optional) — piped input is read in full and hashed into the run's receipt

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `sql.py`

Run SQL queries on CSV, TSV, or tabular data, outputting results as Markdown, JSON, or CSV.

Use when the user wants to query, filter, aggregate, or slice tabular CSV or TSV data with SQL, or large tabular files must be summarized before entering context.

```sh
<skill-dir>/sql.py -p query="<query>" [-p table_source="<table_source>"] [-p table_text="<table_text>"] [-p delimiter=auto] [-p format=markdown]
```

Parameters:
- `query` (string, required) — SQL query to run against the table named 'data' (e.g. 'SELECT status, count(*) FROM data GROUP BY status')
- `table_source` (file, optional) — Host CSV/TSV file mounted at /input/table_source
- `table_text` (string, optional) — Inline CSV/TSV text (or pipe stdin)
- `delimiter` (string, optional, default `auto`) — Column delimiter: auto, comma, tab, pipe, semicolon
- `format` (string, optional, default `markdown`) — Output format: markdown, json, csv
- stdin (optional) — piped input is read in full and hashed into the run's receipt

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.


---
name: diagram
description: 'Render Graphviz DOT with any layout engine. Tools: graphviz. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: 'Requires fragletc and Docker. Hermetic: no network access.'
metadata:
  tags: media
  tools: graphviz.py
---

# Diagram

Render Graphviz DOT with any layout engine.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/graphviz.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `graphviz.py`

Render Graphviz DOT source into an SVG, PNG, PDF, or JSON diagram. Choose a layout engine with engine=dot for hierarchies, neato or fdp for spring layouts, circo for cyclic structures, twopi for radial trees, or sfdp for large graphs. Source comes from the dot parameter, a dot_source file, or stdin, so a model can write the graph and this tool renders it deterministically.

Use when the user has Graphviz DOT source, or wants a graph, tree, flowchart, or network drawn from a description that maps to DOT.

```sh
<skill-dir>/graphviz.py [-p dot="<dot>"] [-p dot_source="<dot_source>"] [-p engine=dot] [-p format=svg] --output diagram
```

Parameters:
- `dot` (string, optional) — Inline DOT source (or pipe stdin)
- `dot_source` (file, optional) — Host DOT file mounted at /input/dot_source
- `engine` (string, optional, default `dot`) — Layout engine (dot, neato, fdp, circo, twopi, sfdp, …)
- `format` (string, optional, default `svg`) — Output format (svg, png, pdf, json, …)
- stdin (optional) — piped input is read in full and hashed into the run's receipt

Outputs:
- `diagram` — copy out with `--output diagram[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.


---
name: doc
description: 'Render Markdown, bundles, and LaTeX to PDF; extract text and render pages from PDF and Office files. Tools: extract-text, latex-to-pdf, markdown-to-pdf, pdf-to-images. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: 'Requires fragletc and Docker. Hermetic: no network access.'
metadata:
  tags: documents
  tools: extract-text.py, latex-to-pdf.sh, markdown-to-pdf.py, pdf-to-images.py
---

# Doc

Render Markdown, bundles, and LaTeX to PDF; extract text and render pages from PDF and Office files.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/extract-text.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `extract-text.py`

Extract readable text out of PDF, DOCX, PPTX, XLSX, ODT, RTF, HTML, and plain-text documents into structured Markdown carrying page, slide, and sheet markers. The format is detected from file content, so no extension is needed; pages selects a 1-indexed subset such as "1-5" or "2,4,7-9" (PDF pages, PPTX slides, XLSX sheets).

Use when the user wants the text of a PDF, Word, PowerPoint, Excel, ODT, RTF, or HTML file, or a document's page count.

```sh
<skill-dir>/extract-text.py -p document="<document>" [-p pages="<pages>"] [-p format="<format>"]
```

Parameters:
- `document` (file, required) — Document mounted at /input/document; format sniffed from content
- `pages` (string, optional) — 1-indexed subset like 1-5 or 2,4,7-9 (pages, slides, or sheets)
- `format` (string, optional) — Force a format instead of sniffing: pdf, docx, pptx, xlsx, odt, rtf, html, text

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `latex-to-pdf.sh`

Compile a LaTeX document to PDF (full TeX Live, offline, deterministic -- no runtime package fetching). Mounts input TeX file via fragletc file-shaped param (:file) to /input/tex_source.

Use when the user has LaTeX source and wants the compiled PDF.

```sh
<skill-dir>/latex-to-pdf.sh -p tex_source="<tex_source>" [-p engine=pdflatex] --output paper.pdf
```

Parameters:
- `tex_source` (file, required) — TeX source mounted at /input/tex_source
- `engine` (string, optional, default `pdflatex`) — TeX engine: pdflatex, xelatex, or lualatex

Outputs:
- `paper.pdf` — copy out with `--output paper.pdf[=<host path>]`

Runs in `ofthemachine/latex@sha256:add4f310e2fb92ebeeb7bc7fa5a95f920fa78adabcc8565301bbb178eac2a0b3`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `markdown-to-pdf.py`

Render Markdown to one PDF with headless Chromium: inline text, a single .md (or .html) file, or a tar/tar.gz/zip bundle of pages plus the images and fonts they reference by relative path. Several pages become one document with page breaks (ordered by manifest.txt/order.txt when present, else by path) and a table of contents. style=reader applies clean reader typography; style=none renders the page exactly as authored, adding only the page box -- for pages that bring their own <style>, like newspapers, posters, and one-sheets.

Use when the user wants a PDF of some Markdown -- one note, a folder of documents compiled into a digest, or a designed page with its own assets and styling.

```sh
<skill-dir>/markdown-to-pdf.py [-p source="<source>"] [-p text="<text>"] [-p page="<page>"] [-p style=reader] [-p toc=auto] [-p title="<title>"] [-p size=A4] [-p margin="<margin>"] --output document.pdf
```

Parameters:
- `source` (file, optional) — A .md or .html file, or a tar/tar.gz/zip bundle of pages and their assets
- `text` (string, optional) — Inline Markdown (or pipe stdin), when there is no source file
- `page` (string, optional) — Render only this entry of a bundle (e.g. index.html); omitted, every .md in the bundle
- `style` (string, optional, default `reader`) — reader (house typography) or none (the page exactly as authored, plus the page box)
- `toc` (string, optional, default `auto`) — Table of contents: auto (when there is more than one page), true, or false
- `title` (string, optional) — Document title, shown as a heading above the contents (reader style only)
- `size` (string, optional, default `A4`) — Paper size (A4, Letter, ...)
- `margin` (string, optional) — Page margin on all sides (default 18mm for reader, 12mm for none)
- stdin (optional) — piped input is read in full and hashed into the run's receipt

Outputs:
- `document.pdf` — copy out with `--output document.pdf[=<host path>]`

Runs in `ofthemachine/headless-browser@sha256:8ac6f2f481f40e32a0b2f8dd7a834fd03197b1556bd8f55b1f167cd71d4877b0`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `pdf-to-images.py`

Render PDF pages to high-resolution PNG images for visual inspection, slide viewing, or multimodal agent review.

Use when the user wants to see the visual layout of a PDF, inspect slides or figures, or convert PDF pages to PNG images.

```sh
<skill-dir>/pdf-to-images.py -p pdf_source="<pdf_source>" [-p page=1] [-p scale=2.0] --output page.png
```

Parameters:
- `pdf_source` (file, required) — PDF file mounted at /input/pdf_source
- `page` (string, optional, default `1`) — 1-indexed page number to render to page.png, or 'all' to bundle every page into pages.tar.gz
- `scale` (string, optional, default `2.0`) — Render scale factor (1.0 = 72 dpi, 2.0 = 144 dpi, 3.0 = 216 dpi)

Outputs:
- `page.png` — copy out with `--output page.png[=<host path>]`
- `pages.tar.gz` — copy out with `--output pages.tar.gz[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.


---
name: github
description: 'GitHub issues and events as data for issue-driven workflows -- the fields of an issue form, and whether an event''s sender is an approver. Tools: check-approver, read-issue-form. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: 'Requires fragletc and Docker. Hermetic: no network access.'
metadata:
  tags: engineering
  tools: check-approver.py, read-issue-form.py
---

# GitHub

GitHub issues and events as data for issue-driven workflows -- the fields of an issue form, and whether an event's sender is an approver.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/check-approver.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `check-approver.py`

Whether a GitHub event's sender is an approver -- one of the people allowed to say "go" to an automated action -- printed as one line naming who approved what, or a failure giving the reason. The approvers file lists one GitHub username per line (# comments; a leading @ or "- " is ignored, so a plain YAML list also works); matching ignores case. label=<name> also requires the event to be that label being applied, so only that label counts as approval. Its receipt is the approval record: which event, which list, which answer.

Use when an issue-driven workflow must act only on approval from specific people -- e.g. before generating anything for a labelled issue, check that whoever applied the label is one of the repository's approvers.

```sh
<skill-dir>/check-approver.py -p event="<event>" -p approvers="<approvers>" [-p label="<label>"]
```

Parameters:
- `event` (file, required) — GitHub event JSON, e.g. $GITHUB_EVENT_PATH for an issues.labeled event
- `approvers` (file, required) — The approvers: one GitHub username per line, # comments allowed
- `label` (string, optional) — If set, the event must be this label being applied (e.g. poem:ready)

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `read-issue-form.py`

The fields of a GitHub issue form as JSON: {"issue": {number, title, author, url, labels}, "fields": {<label_slug>: value}}. GitHub renders a form submission as "### Label" headings with values beneath; each heading becomes a snake_case key, "_No response_" becomes null, and checkbox lists become arrays of the checked options. Accepts a whole GitHub event payload (issues/issue_comment, e.g. $GITHUB_EVENT_PATH) or a bare issue body.

Use when an issue-driven workflow needs the answers from a templated GitHub issue as structured data, e.g. turning a labelled request issue into a request.json for the next step.

```sh
<skill-dir>/read-issue-form.py -p issue="<issue>"
```

Parameters:
- `issue` (file, required) — GitHub event JSON (with .issue) or a bare issue body in Markdown

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.


---
name: home-automation
description: 'Control and query home-automation devices on the LAN -- starting with Roku''s ECP remote-control API. Tools: hue-lights, hue-set, roku-apps, roku-launch, roku-play, roku-press, roku-status, roku-type. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: Requires fragletc and Docker. Network access required.
metadata:
  tags: internet
  tools: hue-lights.py, hue-set.py, roku-apps.py, roku-launch.py, roku-play.py, roku-press.py, roku-status.py, roku-type.py
---

# Home Automation

Control and query home-automation devices on the LAN -- starting with Roku's ECP remote-control API.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/hue-lights.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `hue-lights.py`

List the lights on a Philips Hue bridge via its local v1 API -- one "id\tname\ton\tbri%\treachable\thex" line per light. hex is the bulb's color as #rrggbb at full brightness (brightness stays in its own column), or "-" when the bulb has no color. hs mode is the inverse of hue-set's hex encoding, so a hex this prints can be sent back.

Use when the user asks what lights exist, their names/ids, or whether a light is on, reachable, at what brightness, and what color.

```sh
<skill-dir>/hue-lights.py -p ip="<ip>"
```

Parameters:
- `ip` (string, required) — LAN IP address of the Hue bridge, e.g. 192.168.0.245
- `HUE_USER` (secret, required) — read from the caller's environment, never passed with `-p`; Hue API username from link-button pairing (export HUE_USER on the agent host; delivered as a file, never a param, so it stays out of chat and the ledger)

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `hue-set.py`

Set a Philips Hue light (or all lights) via the bridge's local v1 API -- on/off/toggle, brightness percent, white temperature (kelvin or mired), color by hue degrees + saturation percent or by hex (e.g. hex=#ff8000). Light by numeric id or by name (exact then substring match, like home-automation/roku-launch.py); id=all drives group 0. Pairs with home-automation/hue-lights.py for discovery.

Use when the user asks to turn a light on or off, dim/brighten, or change its color or warmth -- e.g. "turn off the kitchen", "dim living room to 30", "warm the bedroom".

```sh
<skill-dir>/hue-set.py -p ip="<ip>" -p id="<id>" [-p on="<on>"] [-p bri="<bri>"] [-p temp="<temp>"] [-p ct="<ct>"] [-p hue="<hue>"] [-p sat="<sat>"] [-p hex="<hex>"] [-p transition="<transition>"] [-p name="<name>"] [-p delete="<delete>"]
```

Parameters:
- `ip` (string, required) — LAN IP address of the Hue bridge, e.g. 192.168.0.245
- `id` (string, required) — Numeric light id, light name (e.g. "kitchen"), or "all" for every light
- `on` (string, optional) — on, off, or toggle (toggle reads current state first; for "all", any-on means all-off)
- `bri` (string, optional) — Brightness 0-100 percent (0 turns the light off)
- `temp` (string, optional) — White point in kelvin, e.g. 2700 warm / 4000 neutral / 6500 daylight (mutually exclusive with ct)
- `ct` (string, optional) — White point in mired, 153-500 (Hue-native; mutually exclusive with temp)
- `hue` (string, optional) — Color hue in degrees 0-360 (needs a color-capable bulb)
- `sat` (string, optional) — Color saturation 0-100 percent (pairs with hue)
- `hex` (string, optional) — Hex color like #ff8000 or ff8000 (3 or 6 digits, # optional); shorthand for hue+sat, mutually exclusive with them
- `transition` (string, optional) — Fade time in seconds (Hue transitiontime is deciseconds; default bridge 0.4s)
- `name` (string, optional) — New name for the light on the bridge (e.g. name="Living room"; id=all refused)
- `delete` (string, optional) — Set true to DELETE this light from the bridge (numeric id only -- names and all refused; irreversible)
- `HUE_USER` (secret, required) — read from the caller's environment, never passed with `-p`; Hue API username from link-button pairing (export HUE_USER on the agent host; delivered as a file, never a param, so it stays out of chat and the ledger)

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `roku-apps.py`

List the apps installed on a Roku device via its ECP API -- one "id\tname\tversion" line per app, so a caller can find an app's numeric id for home-automation/roku-launch.py.

Use when the user asks what apps or channels are installed on a Roku, or needs an app's numeric id before launching it.

```sh
<skill-dir>/roku-apps.py -p ip="<ip>"
```

Parameters:
- `ip` (string, required) — LAN IP address of the Roku, e.g. 192.168.0.73

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `roku-launch.py`

Launch an app on a Roku device via its ECP API, optionally deep-linking straight into a piece of content when the app supports it (e.g. a Netflix title id) -- pairs with home-automation/roku-apps.py for the app_id.

Use when the user asks to open an app or channel on a Roku, or to jump straight to a specific show or movie inside one via a deep link.

```sh
<skill-dir>/roku-launch.py -p ip="<ip>" -p app_id="<app_id>" [-p content_id="<content_id>"] [-p media_type="<media_type>"]
```

Parameters:
- `ip` (string, required) — LAN IP address of the Roku, e.g. 192.168.0.73
- `app_id` (string, required) — App name (e.g. Netflix, YouTube) or numeric app id from home-automation/roku-apps.py
- `content_id` (string, optional) — App-specific content id to deep-link to (e.g. a Netflix title id from its netflix.com/title/<id> URL)
- `media_type` (string, optional) — Content type for the deep link, e.g. movie, series, episode

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `roku-play.py`

Search Roku's on-device universal search for a title and play the Nth result -- Home to a known state, opens Search, types the query via Lit_ keys, arrows Right into the results grid, opens the chosen result, and presses Select to clear provider-choice/profile screens. NOTE: Roku sunset the /search/browse ECP endpoint in OS 12.0, so this deliberately drives the on-screen keyboard instead; and keypress/Enter is a documented no-op on the OS 15 search screen (focus stays parked on "A", so Select-after-Enter types a stray "a") -- do NOT re-add either. Live-verified 2026-10-03 on Roku Ultra OS 15.3.4 (Home, Down x6 to Search, type, Right x6 to result 1, Select opens result, Select picks provider -> playback); result_index beyond 1 extrapolates one more Right per position and is untested. Timing is fixed-delay and can be thrown off by slow app intro animations -- if playback doesn't start, a manual follow-up home-automation/roku-press.py -p key=Select is the fix, same as a human would do.

Use when the user names a show or movie to play on a Roku without saying which app -- e.g. "play Seinfeld" -- and wants Roku's own cross-provider search used to find and start it, rather than a specific app's deep link.

```sh
<skill-dir>/roku-play.py -p ip="<ip>" -p query="<query>" [-p result_index=1] [-p confirm_selects=1]
```

Parameters:
- `ip` (string, required) — LAN IP address of the Roku, e.g. 192.168.0.73
- `query` (string, required) — Text to search for, e.g. "stargate atlantis"
- `result_index` (string, optional, default `1`) — Which result to open, counting from 1 (left to right in the results row). Only result_index=1 has been verified live; higher values extrapolate.
- `confirm_selects` (string, optional, default `1`) — How many times to press Select after opening the result, to clear a provider-choice and/or profile-picker screen. Some apps need a second Select that a slow intro animation can cause to land too early -- if it doesn't stick, send one more home-automation/roku-press.py -p key=Select by hand.

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `roku-press.py`

Send one or more remote-control key presses to a Roku device over its ECP API (no auth, LAN only) -- the same buttons as the physical remote: navigation, Select, Home, Back, playback, volume, channel. Pass a comma-separated list (e.g. "Down,Down,Down,Select") to send a whole sequence in one call instead of one fraglet run per key.

Use when the user asks to control a Roku -- press a remote button or a sequence of buttons, navigate menus, play/pause, change volume or channel, or go Home -- by its LAN IP address.

```sh
<skill-dir>/roku-press.py -p ip="<ip>" -p key="<key>"
```

Parameters:
- `ip` (string, required) — LAN IP address of the Roku, e.g. 192.168.0.73
- `key` (string, required) — One ECP key name, or a comma-separated sequence, e.g. "Down,Down,Down,Select". Keys: Home, Back, Select, Up, Down, Left, Right, Play, Rev, Fwd, InstantReplay, Info, Search, Enter, Backspace, VolumeUp, VolumeDown, VolumeMute, PowerOff, ChannelUp, ChannelDown

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `roku-status.py`

Ask a Roku what it is doing right now via ECP queries -- the foreground app (query/active-app) plus player state/position/duration when the app reports them (query/media-player). Read-only: touches nothing on screen, safe to run mid-playback.

Use when the user asks what is playing, which app is open, or how far into something the Roku is -- or before a relaunch/resume, to record the app (and position, when available) to go back to.

```sh
<skill-dir>/roku-status.py -p ip="<ip>"
```

Parameters:
- `ip` (string, required) — LAN IP address of the Roku, e.g. 192.168.0.73

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `roku-type.py`

Type free text into a Roku device's currently focused on-screen keyboard field (e.g. a search box) over its ECP API -- sends one keypress/Lit_<char> per character in a single call, instead of one fraglet run per letter. Pairs with home-automation/roku-press.py to navigate to the field first.

Use when the user asks to type a search query or other text into whatever on-screen text field is currently focused on a Roku.

```sh
<skill-dir>/roku-type.py -p ip="<ip>" -p text="<text>"
```

Parameters:
- `ip` (string, required) — LAN IP address of the Roku, e.g. 192.168.0.73
- `text` (string, required) — Text to type into the currently focused on-screen field, e.g. "stargate atlantis"

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.


---
name: image
description: 'Resize, crop, convert, compress, and diff raster images. Tools: chyron, diff, qr, transform. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: 'Requires fragletc and Docker. Hermetic: no network access.'
metadata:
  tags: media
  tools: chyron.py, diff.py, qr.py, transform.py
---

# Image

Resize, crop, convert, compress, and diff raster images.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/chyron.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `chyron.py`

Draw a TV-news lower third as a PNG: a studio backdrop, a red kicker box (BREAKING, LIVE, DEVELOPING), the headline bar, an optional ticker strip along the bottom, and the show's name as the corner bug. A still for a satirical or real broadcast; meme/caption puts text on a meme template instead.

Use when a news-style card, chyron, lower third or "breaking news" banner is wanted for a headline.

```sh
<skill-dir>/chyron.py -p headline="<headline>" [-p kicker=BREAKING] [-p ticker="<ticker>"] [-p show=NEWS] [-p width=1280] [-p mood=on-air] --output chyron.png
```

Parameters:
- `headline` (string, required) — The headline across the bar, one line (long ones are shrunk, then cut with an ellipsis)
- `kicker` (string, optional, default `BREAKING`) — The word in the red box before the headline, e.g. BREAKING, LIVE, DEVELOPING
- `ticker` (string, optional) — Text for the ticker strip along the bottom; empty: no ticker
- `show` (string, optional, default `NEWS`) — The show's name, drawn as the corner bug
- `width` (string, optional, default `1280`) — Image width in pixels (height is 9/16 of it)
- `mood` (string, optional, default `on-air`) — How the anchor looks: on-air (composed), frazzled (hair up, tie loose, sweating) or beaming (a grin)

Outputs:
- `chyron.png` — copy out with `--output chyron.png[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `diff.py`

Compare two images pixel by pixel and report a machine-readable result (RESULT: IDENTICAL or RESULT: DIFFERENT) with the changed-pixel percentage, maximum channel delta, and bounding box of the change, alongside a PNG that tints every changed region red over the after image. Set tolerance to ignore per-channel noise below a 0-255 threshold, such as antialiasing jitter.

Use when the user wants to know whether two images differ, how much, and where -- visual regression checks, before/after comparisons.

```sh
<skill-dir>/diff.py -p before="<before>" -p after="<after>" [-p tolerance=0] --output diff.png
```

Parameters:
- `before` (file, required) — Baseline image
- `after` (file, required) — Comparison image
- `tolerance` (string, optional, default `0`) — Ignore per-channel deltas below this 0-255 threshold

Outputs:
- `diff.png` — copy out with `--output diff.png[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `qr.py`

Make a QR code (PNG or SVG) for a link or any text, computed locally with segno and no network: what it encodes never leaves the container. Text that is a secret (an invite link, a Wi-Fi password) goes on stdin, not in text=: params are written into every receipt in plain text, stdin only as a hash. Prints the code's version and size, and with show=true the code itself, drawn in the terminal.

Use when the user wants a QR code, a scannable link, or a printable code for a URL, an invite, Wi-Fi details or any short text.

```sh
<skill-dir>/qr.py [-p text="<text>"] [-p format=png] [-p scale=8] [-p border=4] [-p error=M] [-p show=false] --output qr.png:optional
```

Parameters:
- `text` (string, optional) — What the code encodes (or pipe it on stdin, which a secret must use)
- `format` (string, optional, default `png`) — png (raster) or svg (vector)
- `scale` (string, optional, default `8`) — Pixels per module (the code's smallest square)
- `border` (string, optional, default `4`) — Quiet zone around the code, in modules (scanners want 4)
- `error` (string, optional, default `M`) — Error correction: L 7%, M 15%, Q 25%, H 30% of the code may be lost and still scan
- `show` (string, optional, default `false`) — Also draw the code on stdout with text blocks, to scan from a terminal
- stdin (optional) — piped input is read in full and hashed into the run's receipt

Outputs:
- `qr.png:optional` — copy out with `--output qr.png:optional[=<host path>]`
- `qr.svg:optional` — copy out with `--output qr.svg:optional[=<host path>]`

Runs in `ofthemachine/python3@sha256:1a6a8e9cd91c93359794245e2a36b883ee54dfef06356ff8be1d4d863ee3823a`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `transform.py`

Resize, crop, convert, and compress images (PNG, JPEG, WebP, GIF, TIFF, BMP), reporting the byte savings on stdout. Set max_dimension to fit the longest edge inside a box while preserving aspect ratio, or give width and/or height directly; crop takes "x,y,w,h" in pixels and is applied before any resize. Shrinks oversized screenshots before they consume an agent's context or get embedded in a PDF.

Use when an image must be resized, cropped, converted to another format, or compressed to a smaller file size.

```sh
<skill-dir>/transform.py -p image="<image>" [-p max_dimension="<max_dimension>"] [-p width="<width>"] [-p height="<height>"] [-p crop="<crop>"] [-p format="<format>"] [-p quality=85] [-p grayscale=false] --output image
```

Parameters:
- `image` (file, required) — Source image mounted at /input/image
- `max_dimension` (string, optional) — Fit longest edge inside this many pixels
- `width` (string, optional) — Target width in pixels
- `height` (string, optional) — Target height in pixels
- `crop` (string, optional) — Crop box as x,y,w,h in pixels (before resize)
- `format` (string, optional) — Output format (PNG, JPEG, WEBP, …); default keeps source
- `quality` (string, optional, default `85`) — JPEG/WebP quality 1-100
- `grayscale` (string, optional, default `false`) — Convert to grayscale when true

Outputs:
- `image` — copy out with `--output image[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.


---
name: llm
description: 'Text from language models (one provider per tool, the API key declared as a secret and the provider''s host fixed; llm/local for a model server on this machine, no key) and llm/prompt, which composes what they read. Tools: cohere, local, prompt. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: Requires fragletc and Docker. Network access required.
metadata:
  tags: internet
  tools: cohere.py, local.py, prompt.py
---

# LLM

Text from language models (one provider per tool, the API key declared as a secret and the provider's host fixed; llm/local for a model server on this machine, no key) and llm/prompt, which composes what they read.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/cohere.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `cohere.py`

One Cohere chat completion (api.cohere.com/v2/chat) from a prompt file or inline prompt, with an optional system prompt file, written to response.md. The host is fixed -- there is no base-URL parameter -- so the API key can only ever be sent to Cohere. seed makes sampling best-effort reproducible; stdout is a one-line summary (model, seed, tokens, finish reason), never the completion.

Use when a workflow step needs text generated by a language model -- a poem, a caption, a summary -- from a prompt file, and a Cohere API key (free trial keys work) is available.

```sh
<skill-dir>/cohere.py [-p prompt="<prompt>"] [-p prompt_text="<prompt_text>"] [-p system="<system>"] [-p model=command-a-03-2025] [-p temperature=0.7] [-p seed=42] [-p max_tokens=1024] [-p thinking_budget="<thinking_budget>"] --output response.md
```

Parameters:
- `prompt` (file, optional) — Prompt file (the user message)
- `prompt_text` (string, optional) — Inline prompt, when there is no prompt file
- `system` (file, optional) — System prompt file
- `model` (string, optional, default `command-a-03-2025`) — Cohere model id
- `temperature` (string, optional, default `0.7`) — Sampling temperature, 0 to 1
- `seed` (string, optional, default `42`) — Sampling seed; same seed and inputs give best-effort identical output
- `max_tokens` (string, optional, default `1024`) — Maximum tokens to generate (a thinking model's thinking counts)
- `thinking_budget` (string, optional) — For a thinking model (e.g. command-a-plus-05-2026): the most tokens it may think before answering, so the answer fits max_tokens; empty: the model's default
- `COHERE_API_KEY` (secret, required) — read from the caller's environment, never passed with `-p`; Cohere API key (trial keys: 1,000 calls/month)

Outputs:
- `response.md` — copy out with `--output response.md[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `local.py`

One chat completion from a local, OpenAI-compatible model server (LM Studio, llama.cpp, Ollama) from a prompt file and an optional system prompt file, written to response.md; no key. With think=false a reasoning model is asked to answer at once (an empty think block is prefilled), and any think block left in the answer is removed. stdout is a one-line summary, never the completion.

Use when a workflow step needs text from a language model running on this machine (LM Studio, llama.cpp, Ollama): no key, no cloud.

```sh
<skill-dir>/local.py [-p prompt="<prompt>"] [-p prompt_text="<prompt_text>"] [-p system="<system>"] -p model="<model>" [-p endpoint="<endpoint>"] [-p temperature=0.7] [-p seed=42] [-p max_tokens=400] [-p think=false] [-p timeout=900] --output response.md
```

Parameters:
- `prompt` (file, optional) — Prompt file (the user message)
- `prompt_text` (string, optional) — Inline prompt, when there is no prompt file
- `system` (file, optional) — System prompt file
- `model` (string, required) — The model's id on the server, e.g. qwen/qwen3.8-27b
- `endpoint` (string, optional) — The server's chat completions URL as the container reaches it; empty: LM Studio on this machine (host.docker.internal, port 11234)
- `temperature` (string, optional, default `0.7`) — Sampling temperature
- `seed` (string, optional, default `42`) — Sampling seed
- `max_tokens` (string, optional, default `400`) — Most tokens to generate
- `think` (string, optional, default `false`) — Let a reasoning model think before it answers
- `timeout` (string, optional, default `900`) — Seconds to wait for the answer: a local server may be busy with another agent's call, or loading the model

Outputs:
- `response.md` — copy out with `--output response.md[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `prompt.py`

The two files an LLM step reads, for llm/cohere's prompt and system: prompt.md (the task, its subject, reference text, constraints) and system.md (the voice or house style, examples). Reference text and examples are length-capped and fenced as material, never instructions, so an earlier step's output (headlines, a transcript, a page) cannot rewrite the task. For poems, poem/prompt knows the forms.

Use as the step before llm/cohere when a request combines a task with text an earlier step produced or with a stored style guide, or whenever the prompt itself should be its own reproducible step.

```sh
<skill-dir>/prompt.py -p task="<task>" [-p subject="<subject>"] [-p context="<context>"] [-p context_file="<context_file>"] [-p context_label=Reference material] [-p constraints="<constraints>"] [-p style="<style>"] [-p style_file="<style_file>"] [-p examples_file="<examples_file>"] --output prompt.md
```

Parameters:
- `task` (string, required) — What the model must produce, in one or two sentences
- `subject` (string, optional) — What it is about, with the concrete names, numbers and events to keep
- `context` (string, optional) — Reference text to work from, inline (often an earlier step's output); context_file for a file
- `context_file` (file, optional) — Reference text to work from, as a file (e.g. news/headlines' headlines.md)
- `context_label` (string, optional, default `Reference material`) — What the reference text is, named in prompt.md
- `constraints` (string, optional) — Hard requirements such as length, form or things to avoid; newline- or semicolon-separated
- `style` (string, optional) — The voice or house style for system.md, inline; style_file for a file
- `style_file` (file, optional) — The voice or house style for system.md, as a file
- `examples_file` (file, optional) — Examples of the wanted output (their voice is borrowed, never their content)

Outputs:
- `prompt.md` — copy out with `--output prompt.md[=<host path>]`
- `system.md` — copy out with `--output system.md[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.


---
name: math
description: 'Small pure computations -- primality, Fibonacci. Tools: fibonacci, is-prime. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: 'Requires fragletc and Docker. Hermetic: no network access.'
metadata:
  tags: computation
  tools: fibonacci.py, is-prime.py
---

# Math

Small pure computations -- primality, Fibonacci.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/fibonacci.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `fibonacci.py`

The Nth Fibonacci number (0-indexed: F(0)=0, F(1)=1). Pure computation, no network.

Use when the user asks for a Fibonacci number by index.

```sh
<skill-dir>/fibonacci.py -p n="<n>"
```

Parameters:
- `n` (string, required) — 0-indexed position of the Fibonacci number to compute

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `is-prime.py`

Check whether a number is prime, and show its smallest prime factor if not. Pure computation, no network.

Use when the user asks whether a number is prime or for its smallest factor.

```sh
<skill-dir>/is-prime.py -p n="<n>"
```

Parameters:
- `n` (string, required) — Integer to test for primality

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.


---
name: meme
description: 'Find meme templates and caption them, with meme-cli. Tools: caption, catalog, list, templates. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: 'Requires fragletc and Docker. Hermetic: no network access.'
metadata:
  tags: media
  tools: caption.sh, catalog.sh, list.sh, templates.sh
---

# Meme

Find meme templates and caption them, with meme-cli.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/caption.sh --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `caption.sh`

Render a caption onto a meme-cli template. lines is a single "|"-delimited string, one caption per box in order, whatever the box count -- a 1-box template is just "one caption", a 2-box is "top|bottom", an 8-box is "a|b|c|d|e|f|g|h". Run templates.sh show <id> first to check the real box count/order.

Use when the user wants a meme rendered from a known template with specific captions.

```sh
<skill-dir>/caption.sh -p template="<template>" -p lines="<lines>" --output meme.png
```

Parameters:
- `template` (string, required) — meme-cli template id (find with templates.sh search/show)
- `lines` (string, required) — Captions joined by |, one per box in template order

Outputs:
- `meme.png` — copy out with `--output meme.png[=<host path>]`

Runs in `ofthemachine/meme@sha256:8a3ac29b110b9471e7688bf8d7bdc12fe83fd49da63a084a3db1a41549b6c57f`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `catalog.sh`

Dump the whole meme catalog in one run: meme-cli list --json. Each template's alias is its id, its field count is the length of text_boxes, and its description is name. The image has no shell, so this is its own fraglet rather than a flag on templates.sh.

Use when a caller needs every template at once — alias, field count, description — to choose one.

```sh
<skill-dir>/catalog.sh
```

Parameters:
- none

Outputs:
- stdout

Runs in `ofthemachine/meme@sha256:8a3ac29b110b9471e7688bf8d7bdc12fe83fd49da63a084a3db1a41549b6c57f`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `list.sh`

Every meme template, one per line: its id, how many captions it takes ("2 boxes") and its name, in columns at least two spaces apart (meme-cli list). For keywords and box geometry, meme/catalog's JSON.

Use when a caller needs the template ids to choose from, as plain lines.

```sh
<skill-dir>/list.sh
```

Parameters:
- none

Outputs:
- stdout

Runs in `ofthemachine/meme@sha256:8a3ac29b110b9471e7688bf8d7bdc12fe83fd49da63a084a3db1a41549b6c57f`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `templates.sh`

Browse meme-cli's template library: templates.sh search <term>, templates.sh show <template> (boxes and their order), templates.sh list (popular templates), or templates.sh llms (meme-cli's guidance for LLMs). Arguments pass straight through to meme-cli; there are no -p parameters.

Use when the user wants to find a meme template, check a template's box count and order, list popular templates, or read meme-cli's guidance for LLMs.

```sh
<skill-dir>/templates.sh
```

Parameters:
- none

Outputs:
- stdout

Runs in `ofthemachine/meme@sha256:8a3ac29b110b9471e7688bf8d7bdc12fe83fd49da63a084a3db1a41549b6c57f`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.


---
name: net
description: 'The host''s place on the network -- its public IP address and where an IP address is. Tools: ip-location, public-ip. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: Requires fragletc and Docker. Network access required.
metadata:
  tags: internet
  tools: ip-location.py, public-ip.py
---

# Net

The host's place on the network -- its public IP address and where an IP address is.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/ip-location.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `ip-location.py`

Where an IP address is, from ip-api.com (no API key; its free tier is plain HTTP, so treat the answer as a hint, not a secret). Prints one line "City, Region, Country (CC) lat,lon tz" -- the City is the shape weather/current.py, weather/forecast.py and web/search.py take as their location. Pass ip= to look up a specific address; omitted, the caller's own public address is located.

Use when a workflow must find out where it is running (which city) before fetching local weather or news, or when the user asks where an IP address is.

```sh
<skill-dir>/ip-location.py [-p ip="<ip>"]
```

Parameters:
- `ip` (string, optional) — IPv4 or IPv6 address to locate; omitted, the caller's own public address

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `public-ip.py`

The host's public IPv4/IPv6 address as the internet sees it, from ifconfig.me (no API key) -- what `curl ifconfig.me` prints, as a fraglet so a workflow can record where it ran. Prints the bare address and nothing else.

Use when the user asks what their public IP is, or a workflow needs the address it is running from -- for example to locate itself with net/ip-location.py.

```sh
<skill-dir>/public-ip.py
```

Parameters:
- none

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.


---
name: news
description: 'Headlines from any RSS or Atom feed, BBC world news by default. Tools: headlines. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: Requires fragletc and Docker. Network access required.
metadata:
  tags: world
  tools: headlines.py
---

# News

Headlines from any RSS or Atom feed, BBC world news by default.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/headlines.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `headlines.py`

The latest headlines from a news feed (RSS or Atom), newest first. Clean markdown list by default, or TSV when format=tsv.

Use when the user wants today's top news or the latest headlines from an outlet, section, or feed, or a briefing, caption, or prompt needs a live headline.

```sh
<skill-dir>/headlines.py [-p feed=feeds.bbci.co.uk/news/world/rss.xml] [-p count=5] [-p format=markdown] --output headlines.md:d=The headlines as the markdown list, whatever format stdout takes, for a later step to read
```

Parameters:
- `feed` (string, optional, default `feeds.bbci.co.uk/news/world/rss.xml`) — RSS or Atom feed URL (https:// is assumed when no scheme is given)
- `count` (string, optional, default `5`) — How many headlines to print
- `format` (string, optional, default `markdown`) — Stdout format: "markdown" for formatted clickable links, or "tsv" for title\tlink\tdate

Outputs:
- `headlines.md:d=The headlines as the markdown list, whatever format stdout takes, for a later step to read` — copy out with `--output headlines.md:d=The headlines as the markdown list, whatever format stdout takes, for a later step to read[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.


---
name: package
description: 'Facts about published software packages -- versions, release dates, licenses, and dependencies from PyPI, npm, crates.io, and Docker Hub. Tools: metadata. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: Requires fragletc and Docker. Network access required.
metadata:
  tags: engineering, internet
  tools: metadata.py
---

# Package

Facts about published software packages -- versions, release dates, licenses, and dependencies from PyPI, npm, crates.io, and Docker Hub.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/metadata.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `metadata.py`

Query package registries (pypi, npm, crates, dockerhub) for latest versions, release dates, licenses, and dependencies.

Use when the user wants to check package versions, verify dependency existence, check release dates, or inspect package metadata.

```sh
<skill-dir>/metadata.py -p registry="<registry>" -p package="<package>" [-p version=latest] [-p format=markdown]
```

Parameters:
- `registry` (string, required) — Registry ecosystem: pypi, npm, crates, dockerhub
- `package` (string, required) — Package or image name (e.g. 'requests', 'express', 'tokio', 'library/alpine')
- `version` (string, optional, default `latest`) — Specific version tag to query, or 'latest'
- `format` (string, optional, default `markdown`) — Output format: markdown or json

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.


---
name: poem
description: 'Poems about any subject -- the prompts a language model (llm/*) writes one from, in a chosen form and voice. Tools: prompt. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: 'Requires fragletc and Docker. Hermetic: no network access.'
metadata:
  tags: computation
  tools: prompt.py
---

# Poem

Poems about any subject -- the prompts a language model (llm/*) writes one from, in a chosen form and voice.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/prompt.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `prompt.py`

The prompts for a poem about any subject: system.md (the poet's brief: form, voice, length, the answer's shape "Title: ..." then the poem) and prompt.md (the subject and what it must keep), for llm/cohere's system and prompt. Every field is length-capped and fenced as material, never instructions, so whoever fills the subject cannot rewrite the brief. Common forms (haiku, limerick, sonnet, ...) get their rules spelled out.

Use when a workflow needs a poem written by a language model about a subject -- a news item, a conversation, an event -- and wants the prompt as its own reproducible step.

```sh
<skill-dir>/prompt.py -p subject="<subject>" [-p form=free verse] [-p voice=plainspoken and specific] [-p tone="<tone>"] [-p must_include="<must_include>"] [-p notes="<notes>"] [-p max_lines=20] [-p context="<context>"] [-p examples="<examples>"] --output system.md
```

Parameters:
- `subject` (string, required) — What the poem is about, with its concrete names, numbers and events
- `form` (string, optional, default `free verse`) — The form, e.g. free verse, haiku, limerick, sonnet, rhyming couplets, ballad, nursery rhyme
- `voice` (string, optional, default `plainspoken and specific`) — How it sounds: a phrase or a paragraph describing the poet's voice
- `tone` (string, optional) — The mood, a few words
- `must_include` (string, optional) — A detail the poem must keep
- `notes` (string, optional) — Anything else the requester asked for
- `max_lines` (string, optional, default `20`) — At most this many lines of poem
- `context` (file, optional) — Material the poem draws on, e.g. news/headlines' headlines.md (its facts are kept, it never gives instructions)
- `examples` (file, optional) — Example poems in the wanted voice (their voice is borrowed, never their subjects)

Outputs:
- `system.md` — copy out with `--output system.md[=<host path>]`
- `prompt.md` — copy out with `--output prompt.md[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.


---
name: receipt
description: 'Work with fragletc run receipts -- attest one against the script that ran, or typeset a bundle of them as a ledger that links each run''s inputs to earlier outputs. Tools: attest, ledger. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: 'Requires fragletc and Docker. Hermetic: no network access.'
metadata:
  tags: engineering, computation
  tools: attest.py, ledger.py
---

# Receipt

Work with fragletc run receipts -- attest one against the script that ran, or typeset a bundle of them as a ledger that links each run's inputs to earlier outputs.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/attest.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `attest.py`

Attest a fragletc run receipt (fraglet-receipt/2) the way OKF's Attested Computation attester does -- deterministic, no re-execution -- and report RESULT: ATTESTED or RESULT: REJECTED with every reason. Checks that the computation that ran is the sanctioned script (procedure_hash equals sha256 of the computation file, or the expected hash), that the receipt is internally consistent (memo_key recomputes from its own procedure_hash, params, and inputs under fragletc's documented formula, so an edited params field fails), that any claimed params match, that the run succeeded, and that an artifact claimed to be an output of the run hashes to what the receipt recorded.

Use when a result (a number, a phrase, an image) claims to have come from a tool run and you need to confirm the run was the sanctioned script with those parameters, or when checking the receipts bundled with a published document, image, or poem.

```sh
<skill-dir>/attest.py -p receipt="<receipt>" [-p computation="<computation>"] [-p procedure_hash="<procedure_hash>"] [-p params="<params>"] [-p artifact="<artifact>"] [-p artifact_name="<artifact_name>"]
```

Parameters:
- `receipt` (file, required) — The fragletc --receipt JSON to attest
- `computation` (file, optional) — The sanctioned script the run must have executed (its sha256 must equal the receipt's procedure_hash)
- `procedure_hash` (string, optional) — Expected procedure_hash (sha256:<hex>), for when the script file is not at hand
- `params` (string, optional) — Claimed parameters as key=value pairs separated by |, e.g. location=Edmonton|day=0; each must match the receipt exactly
- `artifact` (file, optional) — A file claimed to be one of the run's outputs (a figure, a document); its sha256 must appear in the receipt's outputs
- `artifact_name` (string, optional) — Which declared output the artifact claims to be (a relpath under /output); omitted, any output may match

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `ledger.py`

Typeset an archive of fragletc receipts (fraglet-receipt/2) as a ledger: one row per run with its tool, memo key, params, inputs and outputs by content hash, and exit code, in run order. Where a run's input hash is an earlier run's output hash the row says so, which makes the archive a provenance graph a reader can follow by hand. If the archive also carries blobs/<sha256 hex> files, every hash present in it is marked, so the reader knows which bytes travel with the ledger and which are hash-only. Emits an HTML fragment (default) or Markdown to stdout, for embedding in a page such as a Daily Fraglet edition.

Use when a bundle of receipts must be presented to a reader as evidence -- an appendix, a ledger page, a provenance table -- rather than handed over as raw JSON.

```sh
<skill-dir>/ledger.py -p receipts="<receipts>" [-p format=html] [-p prefix=12]
```

Parameters:
- `receipts` (file, required) — tar/tar.gz/zip containing receipts/*.json and optionally blobs/<hex>
- `format` (string, optional, default `html`) — html (a fragment with class="ledger") or md
- `prefix` (string, optional, default `12`) — How many hex characters of each hash to print

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.


---
name: sheet
description: 'Inspect, summarize, and convert spreadsheet workbooks (Excel XLSX, ODS). Tools: convert, inspect. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: 'Requires fragletc and Docker. Hermetic: no network access.'
metadata:
  tags: documents, engineering
  tools: convert.py, inspect.py
---

# Sheet

Inspect, summarize, and convert spreadsheet workbooks (Excel XLSX, ODS).

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/convert.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `convert.py`

Convert a sheet from an Excel (XLSX) or ODS spreadsheet into clean CSV, TSV, or JSON.

Use when the user wants to extract data from an Excel or ODS workbook into a flat format (CSV, TSV, JSON) or save a sheet as a table.

```sh
<skill-dir>/convert.py -p workbook="<workbook>" [-p sheet=1] [-p format=csv] --output sheet.csv
```

Parameters:
- `workbook` (file, required) — Spreadsheet workbook mounted at /input/workbook
- `sheet` (string, optional, default `1`) — 1-indexed sheet index or sheet name to convert (defaults to the first sheet)
- `format` (string, optional, default `csv`) — Output format: csv, tsv, json

Outputs:
- `sheet.csv` — copy out with `--output sheet.csv[=<host path>]`
- `sheet.tsv` — copy out with `--output sheet.tsv[=<host path>]`
- `sheet.json` — copy out with `--output sheet.json[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `inspect.py`

Inspect spreadsheet workbooks (XLSX, ODS), listing sheet names, row and column dimensions, and header columns.

Use when the user wants to see the structure, sheets, dimensions, or column names of an Excel or ODS spreadsheet without reading all rows.

```sh
<skill-dir>/inspect.py -p workbook="<workbook>" [-p format=markdown]
```

Parameters:
- `workbook` (file, required) — Spreadsheet workbook mounted at /input/workbook
- `format` (string, optional, default `markdown`) — Output format: markdown or json

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.


---
name: token
description: 'Count and chunk text by LLM token budget (OpenAI tiktoken encodings). Tools: chunk, count. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: Requires fragletc and Docker. Network access required.
metadata:
  tags: engineering
  tools: chunk.py, count.py
---

# Token

Count and chunk text by LLM token budget (OpenAI tiktoken encodings).

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/chunk.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `chunk.py`

Split text into token-budgeted chunks using OpenAI tiktoken encodings, preferring paragraph boundaries and hard-splitting only paragraphs that exceed the budget on their own. Each chunk is introduced by a "[chunk i/n tokens=k]" marker line, and overlap carries that many tokens of tail context into the next chunk so meaning is not severed mid-thought. Companion to counter, which measures what this splits.

Use when text is too large for one prompt and must be split into token-budgeted pieces that respect paragraph boundaries.

```sh
<skill-dir>/chunk.py [-p text="<text>"] [-p text_source="<text_source>"] [-p max_tokens=1000] [-p overlap=100] [-p encoding=cl100k_base]
```

Parameters:
- `text` (string, optional) — Inline text to chunk (or pipe stdin)
- `text_source` (file, optional) — Host file mounted at /input/text_source
- `max_tokens` (string, optional, default `1000`) — Token budget per chunk
- `overlap` (string, optional, default `100`) — Tail tokens carried into the next chunk
- `encoding` (string, optional, default `cl100k_base`) — tiktoken encoding or model name
- stdin (optional) — piped input is read in full and hashed into the run's receipt

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `count.py`

Calculate BPE token counts and token statistics for text or files using OpenAI tiktoken tokenizers (cl100k_base or o200k_base).

Use when the user asks how many tokens some text or file is, or a prompt must be checked against a token budget.

```sh
<skill-dir>/count.py [-p text="<text>"] [-p encoding=cl100k_base]
```

Parameters:
- `text` (string, optional) — Inline text to tokenize (or pipe stdin)
- `encoding` (string, optional, default `cl100k_base`) — tiktoken encoding or model name
- stdin (optional) — piped input is read in full and hashed into the run's receipt

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.


---
name: trivia
description: 'Advice, cat facts, jokes, and on-this-day anniversaries from free public APIs. Tools: advice, cat-fact, joke, on-this-day. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: Requires fragletc and Docker. Network access required.
metadata:
  tags: world
  tools: advice.py, cat-fact.py, joke.py, on-this-day.py
---

# Trivia

Advice, cat facts, jokes, and on-this-day anniversaries from free public APIs.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/advice.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `advice.py`

A random piece of advice (Advice Slip API, no API key).

Use when the user asks for a random piece of advice, or a caption or meme needs one.

```sh
<skill-dir>/advice.py
```

Parameters:
- none

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `cat-fact.py`

A random cat fact (catfact.ninja, no API key).

Use when the user asks for a cat fact, or a caption or meme needs one.

```sh
<skill-dir>/cat-fact.py
```

Parameters:
- none

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `joke.py`

Fetch a random humorous joke or one-liner (icanhazdadjoke.com, no API key).

Use when the user asks for a joke or one-liner, or a caption or meme needs one.

```sh
<skill-dir>/joke.py
```

Parameters:
- none

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `on-this-day.py`

Notable events that happened on a month and day in history, from Wikipedia's "On this day" feed (Wikimedia API, no key). One "YEAR<TAB>text" line per event, most recent first, count-limited, so a briefing can pick the one that rhymes with today.

Use when the user asks what happened on this day in history, or a newspaper, briefing, or caption wants an anniversary for a given date.

```sh
<skill-dir>/on-this-day.py -p month="<month>" -p day="<day>" [-p count=8]
```

Parameters:
- `month` (string, required) — Month as a number, 1-12
- `day` (string, required) — Day of the month, 1-31
- `count` (string, optional, default `8`) — How many events to print

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.


---
name: weather
description: 'Live current conditions and three-day forecasts for any place. Tools: current, forecast, frog. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: Requires fragletc and Docker. Network access required.
metadata:
  tags: world
  tools: current.py, forecast.py, frog.py
---

# Weather

Live current conditions and three-day forecasts for any place.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/current.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `current.py`

Real current conditions for any city, via wttr.in's compact one-line format (%l: +%t %C) -- genuinely current, not a canned response. Outputs a single short phrase ready for captions or notifications, avoiding unrenderable emoji glyphs.

Use when the user asks what the weather is like right now somewhere, or a caption or notification needs a live conditions phrase.

```sh
<skill-dir>/current.py -p location="<location>"
```

Parameters:
- `location` (string, required) — City, region, or landmark, e.g. Vancouver or Mount Fuji

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `forecast.py`

Three-day weather forecast for a city, region, or landmark (Open-Meteo geocoding + forecast, no API key). Companion to weather/current.py, which only covers right now and takes the same location parameter. Pass day=0/1/2 to print just today, tomorrow, or day after; omitted prints all three days.

Use when the user asks about tomorrow's or the next few days' weather somewhere, or wants a planning-grade forecast rather than current conditions.

```sh
<skill-dir>/forecast.py -p location="<location>" [-p day="<day>"]
```

Parameters:
- `location` (string, required) — City, region, or landmark, e.g. Vancouver or Mount Fuji
- `day` (string, optional) — 0 today, 1 tomorrow, 2 day after; omit for all three

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `frog.py`

A weather frog (Wetterfrosch): how nice one day will be somewhere, as a rung on its ladder from 0 (stay in) to 1 (glorious), plus a one-line croak saying why and whether to take an umbrella, and the chance of rain (rain.txt, 0 to 1) a body can drink from. Open-Meteo, no API key. The rung is a number a body can climb by; the croak is what it says.

Use when an agent's body or a morning card wants the forecast as one number and one line rather than a table.

```sh
<skill-dir>/frog.py -p location="<location>" [-p day=1] --output rung.txt
```

Parameters:
- `location` (string, required) — City, region, or landmark, e.g. Toronto
- `day` (string, optional, default `1`) — 0 today, 1 tomorrow, 2 the day after

Outputs:
- `rung.txt` — copy out with `--output rung.txt[=<host path>]`
- `croak.txt` — copy out with `--output croak.txt[=<host path>]`
- `rain.txt` — copy out with `--output rain.txt[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.


---
name: web
description: 'Search the web and turn a page into Markdown, PDF, a screenshot, or its metadata; find an existing archived snapshot. Tools: archive-snapshot, page-metadata, page-to-markdown, page-to-pdf, screenshot, search, wiki-summary. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: Requires fragletc and Docker. Network access required.
metadata:
  tags: internet, documents
  tools: archive-snapshot.py, page-metadata.py, page-to-markdown.py, page-to-pdf.py, screenshot.py, search.py, wiki-summary.py
---

# Web

Search the web and turn a page into Markdown, PDF, a screenshot, or its metadata; find an existing archived snapshot.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/archive-snapshot.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `archive-snapshot.py`

Look up whether archive.ph already has a snapshot of a URL -- GET /newest/<url> and report its Location header on a redirect. Lookup only: never submits a new snapshot, so it can't be used to force-archive something that isn't already there. Prints nothing (not an error) when no snapshot exists -- the caller falls back to the original link.

Use when a link may be paywalled or gone and the user wants an existing archive.ph snapshot of it, without creating one.

```sh
<skill-dir>/archive-snapshot.py -p url="<url>"
```

Parameters:
- `url` (string, required) — URL to look up on archive.ph

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `page-metadata.py`

Fetch a URL and extract its <title> and Open Graph tags (og:title, og:description, og:image) -- stdlib html.parser only, no external service.

Use when the user wants a page's title, description, or preview image, or a link needs a caption without fetching the whole article.

```sh
<skill-dir>/page-metadata.py -p url="<url>"
```

Parameters:
- `url` (string, required) — Page URL to fetch

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `page-to-markdown.py`

Extract clean, readable Markdown article text from any web page using Trafilatura, stripping ads, navigations, sidebars, and boilerplate.

Use when the user wants the article text of a web page, or a page must be read without ads, navigation, and boilerplate.

```sh
<skill-dir>/page-to-markdown.py -p url="<url>" --output article.md
```

Parameters:
- `url` (string, required) — Page URL to extract

Outputs:
- `article.md` — copy out with `--output article.md[=<host path>]`

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `page-to-pdf.py`

Render a webpage to a PDF (headless Chromium via Playwright) -- the print-to-PDF cousin of web/screenshot.py. Pass headers=<json object> to send extra request headers, as in web/screenshot.py.

Use when the user wants a PDF of a web page as the browser would print it, including layout and images.

```sh
<skill-dir>/page-to-pdf.py -p url="<url>" [-p headers="<headers>"] --output page.pdf
```

Parameters:
- `url` (string, required) — Page URL to render
- `headers` (string, optional) — JSON object of extra non-secret HTTP headers (e.g. Accept-Language); recorded in plaintext in receipts, so never credentials

Outputs:
- `page.pdf` — copy out with `--output page.pdf[=<host path>]`

Runs in `ofthemachine/headless-browser@sha256:f79c496c6737113c0f6e2d648474a67fb1a416fa34c22220d5714d0b7c6a6036`; network required — output depends on live external state; do not cache indefinitely.

### `screenshot.py`

Capture a full-page PNG screenshot of a webpage (headless Chromium via Playwright). Pass headers=<json object> to send extra request headers. settle_ms (default 2000) is an extra wait after page load, for pages whose real content only appears after their own async JS runs.

Use when the user wants a picture of a rendered page, or a visual check of a URL rather than its text.

```sh
<skill-dir>/screenshot.py -p url="<url>" [-p headers="<headers>"] [-p settle_ms=2000] --output page.png
```

Parameters:
- `url` (string, required) — Page URL to capture
- `headers` (string, optional) — JSON object of extra non-secret HTTP headers (e.g. Accept-Language); recorded in plaintext in receipts, so never credentials
- `settle_ms` (string, optional, default `2000`) — Extra wait after page load for async JS content

Outputs:
- `page.png` — copy out with `--output page.png[=<host path>]`

Runs in `ofthemachine/headless-browser@sha256:f79c496c6737113c0f6e2d648474a67fb1a416fa34c22220d5714d0b7c6a6036`; network required — output depends on live external state; do not cache indefinitely.

### `search.py`

Search the web through DuckDuckGo and print one "title<TAB>url<TAB>snippet" result per line, with no API key required. Set site to constrain results to a single domain, timelimit to d, w, m, or y for recency, and region for locale-weighted results. Pairs with page-to-markdown to turn a query into full article text.

Use when the user wants web search results, recent news about a topic or place, or pages from a specific site, and no API key is available.

```sh
<skill-dir>/search.py -p query="<query>" [-p max_results=10] [-p site="<site>"] [-p region=wt-wt] [-p timelimit="<timelimit>"]
```

Parameters:
- `query` (string, required) — Search query
- `max_results` (string, optional, default `10`) — Maximum results to print
- `site` (string, optional) — Restrict results to this domain
- `region` (string, optional, default `wt-wt`) — DuckDuckGo region code (wt-wt = worldwide)
- `timelimit` (string, optional) — Recency filter: d, w, m, or y

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; network required — output depends on live external state; do not cache indefinitely.

### `wiki-summary.py`

The lead summaries of the Wikipedia articles that best match one or more topics (Wikipedia's own search, then each article's page summary), written to summary.md as each article's title, link and a few paragraphs. Topics are separated by semicolons (cat behavior; object permanence) and share the byte budget. An article whose title shares no word with its topic is not taken (a search for a sentence finds noise), so a topic may find nothing; a query nothing matches still succeeds, and summary.md says no article was found, so a workflow that cites it goes on with no evidence rather than stopping. A rate limit or a server error exits 75 (temporary: fragletc --retry). Unlike web/page-to-markdown it needs no URL, only words.

Use when a workflow step needs encyclopedic background on subjects named in a few plain words -- a topic, a dish, a person -- as a file a later step reads. Name subjects, not sentences: "cat behavior", not "cats who knock things off tables".

```sh
<skill-dir>/wiki-summary.py -p query="<query>" [-p language=en] [-p max_bytes=3000] --output summary.md
```

Parameters:
- `query` (string, required) — What to look up: a topic in a few plain words, or several separated by semicolons, e.g. cat behavior; object permanence
- `language` (string, optional, default `en`) — Wikipedia language code, e.g. en, fr, de
- `max_bytes` (string, optional, default `3000`) — At most this many bytes of summary text in all, shared by the topics

Outputs:
- `summary.md` — copy out with `--output summary.md[=<host path>]`

Runs in `ofthemachine/python3@sha256:59784cff1945b7d6093a591b5e5292b8c989f0691af0494fbbe1c6b8083a16cb`; network required — output depends on live external state; do not cache indefinitely.


---
name: words
description: 'Text games and transforms -- palindromes, ROT13, Wordle solving. Tools: is-palindrome, rot13, solve-wordle. Use when a request needs any of these; each tool''s own trigger is in SKILL.md.'
compatibility: 'Requires fragletc and Docker. Hermetic: no network access.'
metadata:
  tags: computation
  tools: is-palindrome.py, rot13.py, solve-wordle.java
---

# Words

Text games and transforms -- palindromes, ROT13, Wordle solving.

Every tool below is one executable file beside this `SKILL.md`, in the directory the commands below call `<skill-dir>`. Run it directly. Two host requirements: [`fragletc`](https://github.com/ofthemachine/fraglet) (`curl -fsSL https://raw.githubusercontent.com/ofthemachine/fraglet/main/install.sh | sh && fragletc version`) and Docker; the image, parameters, outputs and network reach are declared in the file itself. Before running a tool, print its contract:

```sh
<skill-dir>/is-palindrome.py --fraglet-help
```

Parameters are passed as `-p name=value` (a `file` parameter takes a host path); declared outputs are copied out with `--output <name>[=<host path>]`. A missing required parameter fails host-side with exit 2 before any container starts; otherwise the tool's own exit code is the run's. A declared output not named with `--output` is produced and discarded (a stderr note says what you could have copied). Add `--receipt run.json` (or set `FRAGLETC_RECEIPT_DIR`) to record the run: the receipt carries the tool's `procedure_hash`, image digest, parameters, and every input and output by content hash, and `receipt/attest.py` can verify it later without re-running anything.

## Tools

### `is-palindrome.py`

Check whether text is a palindrome, ignoring case, spaces, and punctuation. Pure computation, no network.

Use when the user asks whether a word or phrase is a palindrome.

```sh
<skill-dir>/is-palindrome.py -p text="<text>"
```

Parameters:
- `text` (string, required) — Text to check

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `rot13.py`

ROT13 a string (its own inverse -- run it twice to get the original back). Pure computation, no network.

Use when the user asks to ROT13 encode or decode text.

```sh
<skill-dir>/rot13.py -p text="<text>"
```

Parameters:
- `text` (string, required) — Text to encode or decode

Outputs:
- stdout

Runs in `ofthemachine/python3@sha256:a015b4f9f0e7c1648f8fcd4164f6a296dd3c9189404f88f333a9764d08d13522`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

### `solve-wordle.java`

Filter possible 5-letter Wordle answers given one or more guess+feedback rounds, using 100hellos/java's real wordalytica fluent WordSet API and word list (not a reimplementation). clues is "guess:result|guess:result|...", each result a 5-char G/Y/X string matching that guess letter-for-letter (G=green/correct spot, Y=yellow/wrong spot, X=gray/absent), e.g. "crane:GYXXX|mount:XXGXY". Report the raw colors you see -- this tool does the Wordle-logic-to-predicate translation, not you.

Use when the user is solving a Wordle and reports the colours from one or more guesses.

```sh
<skill-dir>/solve-wordle.java -p clues="<clues>"
```

Parameters:
- `clues` (string, required) — guess:result rounds joined by |; result is 5 chars of G/Y/X, e.g. crane:GYXXX|mount:XXGXY

Outputs:
- stdout

Runs in `100hellos/java@sha256:2b8b7b5817381f6d9460e2b4a124ad5f0ca01d668d4db084690a45939831b909`; hermetic — `network=none`; a run is a pure function of its inputs and safe to memoize.

