Examples
Every so often the cheapest version of a tool is the one your agent writes itself. This is one of those, written to settle a question nobody should have to spend a session on: how do I get cat pictures into the terminal?
The uck is
ddg
in kensand/kensand-fcli-ucks,
and it came out of one agent session — the prompt was "make me an f command
for cat pictures". Everything below is a real artifact from that session, not a
reconstruction: the file, the help text, the installed path. Run the commands and
you get the same output.
What it does
f ddg — search DuckDuckGo
f ddg <query...> web results (numbered: title / url / snippet)
f ddg images <query...> image-oriented results
f ddg open <query...> open the results page in the browser
options: --json --n <k> --region us-en --safe 0|1|2 --lite
--timeout ms --retries <k> --no-block (fallback: open in browser)
note: DDG rate-limits server-side clients (HTTP 202 'anomaly' page);
the cooldown is IP-based, usually a few minutes.
That is the whole surface, and it is f ddg --help — the file the uck ships,
not a page in a config. Eight lines that tell you everything the tool can do,
printed on demand, costing nothing until you ask.
What it is
Three files, and the smallest one is the interesting one:
| file | lines | bytes | role |
|---|---|---|---|
index.js |
266 | 10171 | the command |
SKILL.md |
50 | 2260 | what the session learned, for next time |
package.json |
6 | 169 | type: module — and no dependencies |
No node_modules. fetch and a regular expression do the work. A uck is a
directory with an index.js that exports register(ctx), so the entire
implementation of "search DuckDuckGo" is this:
export function register(_ctx) {
return {
name: "ddg",
desc: "search DuckDuckGo: f ddg [images|open] <query> [--json --n --region --no-block]",
skills: [{ name: "f-ddg", path: path.join(here, "SKILL.md") }],
run: async (argv, _args) => {
/* parse, fetch, parse again, print */
},
};
}
name is the word after f. desc is what f search ranks. run is the
command. There is no manifest, no schema, no server to keep alive, and no
registration step — dropping the directory into the store makes f ddg work on
the next invocation.
The part that is worth the trip
An afternoon of hitting an API teaches you things that do not fit in a help message. The session found that DuckDuckGo does not rate-limit politely:
$ f ddg cat pictures
f ddg: blocked by DuckDuckGo rate limit (HTTP 202 anomaly page). The cooldown is
IP-based and can last tens of minutes to hours from a datacenter IP; wait, or use
--no-block to open the search in your browser instead.
A blocked search returns 202, not 429 — a status that means "accepted", with an HTML challenge page in the body. Nothing about that is guessable, and a naive client reads it as success and parses zero results. So the uck detects the challenge, refuses to retry into it, and says what the cooldown actually is.
Where that knowledge ends up is the point. It goes in ddg/SKILL.md:
The cooldown is IP-based, not per-request: once you trip it, every DDG endpoint (html, lite, i.js JSON API) stays blocked for a long window […] Retrying faster or with different params does nothing.
If results ever come back empty without a block message, DDG changed the markup: check
curl -s 'https://html.duckduckgo.com/html/?q=test' | grep result__aand update the regexes inindex.js.
A skill is a markdown file f loads into context on demand, and the uck
declares its own — that skills: line above means the next agent to touch this
gets the diagnosis without rediscovering it. The regexes will eventually rot when
DuckDuckGo changes its markup — that is the read of the file, not its words, but
the file draws the same conclusion: it names the symptom, the one-line check, and
which lines to edit. That is the difference between a script you rewrite every
six months and a tool that accumulates.
Install it
f config add ucks https://github.com/kensand/kensand-fcli-ucks.git
f up
f ddg cat pictures
f config add ucks <source> accepts a git repo, a local directory, or an npm
package; f up fetches every configured source into ~/.f/ucks/. The bucket is
named after the source — the last path segment of the URL, minus .git — so it
is a live git clone, and the installed command is the repo you can read and
blame:
$ ls ~/.f/ucks/kensand-fcli-ucks/ddg/
SKILL.md index.js package.json
Three committed files, plus a package-lock.json that f up materialises when it
installs the bucket. The bucket is a clone, so git blame on an installed command
works, and f up resets it to the remote — which is why publishing a uck means
pushing, not merely committing.
Installing someone else's uck means running their code with your privileges — ucks are plain Node with no sandbox, and this one is a personal bucket, not a vetted registry. Read it first. It is 266 lines and it is right there.
Write your own
The Quickstart has the eight-line template and the three commands
that register it. What a real uck adds over the template is worth copying from
ddg/index.js
instead:
- a
USAGEstring. Every flag fits in eight lines, so--helpis the whole manual and there is no second place to keep in sync; - argument parsing that survives
--and a value after a flag. Sixteen lines, no dependency; a uck that needsminimistis a uck that needsnode_modules; - an error that names the fix.
no results parsed (DDG layout change?) — try --lite, notexit 1. Compareblocked by DuckDuckGo rate limit (HTTP 202 …), which tells you what to do and why retrying will not help; skills: [{ name, path }], so the file that carries what you learned loads with the uck instead of living in a terminal's scrollback.
Ask an agent for the thing you keep doing by hand — the third curl to the same
endpoint this week — and ask it to leave a uck behind. The contract is on the
Ucks page, and Recipes walks through a second
case: an API that returned a zip where a JSON wrapper assumed text.