---
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.
