Three parallel trees documented the same ecosystem: omp-docs/skills/
(two overview pages), tools/npx-skills/ (10 pi-era npm pages), and
tools/vercel-labs-skills/ (11 CLI pages), plus a fourth leaderboard page
at engineering/skills-ecosystem.md. Verbatim overlap (identical SKILL.md
field tables in skills-spec.md vs skill-format.md; 13-agent vs 68-agent
copies of the same upstream table). Consolidated to four concept pages:
- skills/agent-skills.md: standard, format, loading, authoring (merges
skills-spec, skill-format, skill-file-structure, skill-loading,
best-practices, skills-vs-extensions)
- skills/skills-cli.md: CLI reference (merges commands, source-formats,
installation-scope, skill-discovery, lock-file, env-variables,
agent-support, related-links)
- skills/store-wiring.md: moved, fleet ops, links retargeted
- skills/ecosystem.md: replaces skills-ecosystem.md; stale 2026-08-12
top-50 table dropped, replaced with a live top-10 re-queried from the
skills.sh API tonight and the API contract re-verified (zero-based,
200/page, {skills,total,hasMore,page}, total 9909)
All facts re-verified 2026-10-19 against primary sources:
agentskills.io, vercel-labs/skills README + src/cli.ts (command set,
--full-depth) + src/skill-lock.ts (v3 lock, XDG path, wipe-on-old),
live skills.sh API. Deleted superseded core/index-doc.md (old pi-era
docs index). Retargeted all inbound links (tools/index, engineering x3,
packages x3, pi/skills, core/index). Pi-era npm skill packaging is
listed as archived under /pi/.
Refs #29
- references/okf-spec.md: replace v0.2 note with the deltas verified
against upstream SPEC.md 2026-10-19 (timestamp->generated.at and
# Citations->sources are the two breaking changes; trust fields and
root-index okf_version are additive; bundle stays v0.1).
- index.md: restore the agentic-web-research section lost in the
2026-08-28 rebuild and link log.md (index-coverage doctrine).
- gen-keybinds.sh emits OKF frontmatter so its generated artifact
(tools/niri/keybindings.md, regenerated, 120 bindings) passes kb-lint;
test added red->green.
- fix the two broken [[niri]] wikilinks (handy, noctalia-shell).
Refs #29
Answers spoken with /say were verbatim markdown-cleaned text while the
built-in vocalizer speaks prose rewritten by a small model. Port that
enhancer (bundle Qyr/T6o: same prompt, 1536 tokens, 6 s, 4000-char
window, null-fallback/empty-skip contract) and resolve its model from
modelRoles.tiny exactly as the harness does, so auto-speak sounds like
the enhanced TUI voice instead of a pager. agent_end now also speaks the
last assistant message's thinking blocks as their own unit before the
answer; narration-flagged thinking counts as answer text. Both knobs are
menu-toggleable, persisted, and env-overridable; the fixture gains a
chat route (echo/prose) and seven scenarios cover the round-trip, the
404 fallback, ordering, the kill switches and role resolution (22 green,
58 suite-wide; live smoke through real frank-zealot + frank-tts).
Refs #27
agent_end awaited one whole-answer synthesis; long answers hit the
harness 30s extension-handler timeout (handler timed out after 30000ms)
and the single frank-tts request was the stall. Port the built-in
speak-aloud vocalizer's utterance segmenter (fHe in dist/cli.js) so
segmentation matches the known-working stock path: [.!?…]-run
boundaries, abbreviation/decimal/inline-code guards, fenced code and
tables swallowed, markup cleaned. Play segment N to player exit before
synthesizing N+1 (audio never stacks); fire-and-forget the chain so
utterances outlive the handler timeout; a run token retires superseded
chains. DANKVOICE_MAX becomes a per-answer budget of whole segments;
stripForSpeech is gone. Refs #23 follow-up.
Bare /say and /say menu open a ctx.ui.select settings surface: auto-speak
toggle, voice from the frank-tts roster, PipeWire output device
(pw-play --target / paplay --device=), player binary, spoken cap, and a
test phrase. Choices persist to ~/.omp/cache/dankvoice.json (env wins
over file); detectPlayer becomes availablePlayers + playerFor. Fixes
the silent-route failure mode where synthesized audio played into an
offline Bluetooth sink. 15/15 dankvoice bats, 51/51 suite, live pty
TUI smoke armed the footer and wrote the settings file.
Codifies the limits set in agent/config.yml 2026-10-19: task concurrency 2,
no nested subagent spawns (maxRecursionDepth 1 - and why 0 must never be
set), 30-min runtime / 120-request budgets, isolation opt-in enabled,
completion probes off, 600s tool timeout ceiling, and per-provider
in-flight caps (archon 3, dragoon 2, zealot 3) keyed by models.yml provider
ids with their per-machine scope caveat. Small docs-only change; no issue
opened per trunk-based small-fix exemption.
Every speak-aloud path in the harness gates `--voice` against the bundled
Kokoro enum, so the frank-tts cloned voices could only ever produce files.
`agent/extensions/` auto-loads, so one tracked extension adds the missing
transport: `/say <text>`, `/say on|off` (narrate the final answer at
`agent_end`, silent when the harness schedules a continuation),
`/say voice|voices|stop|status` — OpenAI speech POST plus playback through
pw-play/paplay/ffplay. The endpoint and served id come from the
`api: openai-speech` row of `agent/models.yml`, so the file carries no host
and no secret; markdown is stripped, over-long utterances are cut at a
sentence bound, and the temp WAV dir is always removed.
Verified live in a real TUI session on the workstation (roster
narrator1/narrator2/narrator3; 2.08 s and 1.44 s WAVs played; auto-speak
spoke each finished answer, 1.20 s WAV; unknown voice answers with the
roster). Black-box seam `tests/dankvoice.bats` (12 tests) drives the
extension against a fixture speech endpoint and a stub player.
cwd: /home/blank/.omp/wt/feat-21-dankvoice
session: wt-20261017-181502-6d1fc1f
'Too Claudish': drop the aside ('the gotchas no doc confesses') and the
simile ('watches it fall'); lead with the constraint itself. Facts
unchanged: exclusive dialog, scouts before ask, Esc ends the run, the
ledger survives.
The ask tool's recommended flag only labels option 0; the reply always
names the selected options, so 'the user's single Enter accepts it'
overclaimed a default-accept mechanic that does not exist. Stated
truthfully: the label invites one-glance acceptance, the reply is
self-documenting.
- opening restores 'shared understanding' alongside 'nothing is
silently assumed', and 'Map this as a design tree'
- cluster rationale restated: tight clusters keep each scout aware of
possible adjacencies
- web_search: explicit 'do not delegate to a subagent'
- 'Done' heading -> 'Definition of Done'
Read all 36 upstream skills, then rewrote to their house style per
writing-for-agents' own levers: leading words as tokens (frontier,
brief, ledger, artefact, scout), vocabulary-first and used exactly,
positive phrasing with prohibitions kept only as hard guardrails,
completion criteria sharpened to checkable+exhaustive ('counted before
sending', 'frontier empty and nothing sits blocked'), zero history,
gotchas the environment cannot confess kept inline. All settled
behaviour from the grilling-on-grilling session survives intact.
- drop provenance blockquote and the absorbed-law attribution: the skill
is instructions, not a history
- 'concurrency is capped' replaces the 3-scout figure of one machine
- completion distillate: project's knowledge base or a log markdown file,
not a command-center-specific path (skill travels outside this repo)
Rewritten per grilling-on-grilling (2026-10-18, all branches settled via
ask rounds): ask tool is the default round vehicle (one artefact per
question, recommended:0 = bare-yes semantics, hybrid boundary ask-default
/ prose-exception); todo as visible decision tree (phase=branch, blocked
reasons) + durable local://grilling-state.md ledger surviving the
Esc-aborts-the-run path; scout=environment facts (spawn-before-ask,
exclusive concurrency), web_search=world facts, inline=cheap lookups;
completion gate = summary + one closing ask, then distilled decisions
land in omp-docs/log.md via branch -> PR.
Absorbs managed skill one-decision-per-ask-question (Frank's choice;
reworded: ideas heavily encouraged via own atomic question, ban is on
smuggling into option text only). Managed skill deleted here; heartbeat
drops it from the live tree.
Observed failure mode: tracking flips land in one batch at the end of a
task bill, so the operator's cockpit view stays frozen for the whole run.
Rule pins the mechanics: init before first substantive step, done/start
batched with the step they describe, block-with-reason on stalls, no
lone todo calls. Global tier (APPEND_SYSTEM.md), every session affected.
omp's skill scanner ignores agents/*.yaml (Eve/Codex binding metadata
carried along by the skills CLI store). The file kept vanishing from the
live tree to a background sweep; an authored omp skill does not need it.
Refs #16
Retroactive provenance: the 10 pi-era skill snapshots were byte-identical
to upstream. Canonical installs now live in ~/.agents/skills tracked by
~/.agents/.skill-lock.json (mattpocock/skills x38 after grilling removal,
find-skills from vercel-labs/skills).
Repo tier is authored overrides only: clear all 10 tracked upstream
snapshots; omp loads the store directly through the agents provider
(skills.enableAgentsUser, default on). grilling returns as a real
directory — extracted from the store (CLI + lockfile pruned) so Frank can
customize it without skills update resurrecting a twin.
Docs: skill-store-wiring.md (+index). Pre-cutover snapshot of the old
tracked dirs at /tmp/agent-skills-snap-20261018.
Frank's outline restyle: focus-ring red #e01b24 -> #ffb000 -> #ff8c00
(orange), thickness 2 -> 4 in base layout.kdl. The visible ring is
painted by noctalia.kdl, included LAST in config.kdl — its focus-ring
active/urgent colors moved to #ff8c00 too; tab-indicator, insert-hint,
and recent-window highlights deliberately stay red.
noctalia.kdl was hand-written live-only (Oct 14, no repo copy — the
override that silently beat every layout.kdl edit); first durable copy
lands in the zz-blankpad mirror.
Frank veto: DirectoryNotEmpty re-fires on every file event (GUI writes,
wallpaper shuffle) un-debounced -> hundreds of heartbeat spawns/day.
The sweep is cheap (57 ms CPU) but the trigger design was event spam.
Exposure-window fix is an open design question; timer unchanged.
Timer-only heartbeat left GUI dotfiles edits uncommitted for up to 59
minutes; a trunk-sync session clearing the dirty tree on 2026-10-18
destroyed a month of uncommitted noctalia bar layout inside that gap.
live-sync.path (DirectoryNotEmpty on dotfiles/) fires the existing
flock-guarded oneshot within seconds of any repo-side dotfiles write,
shrinking the exposure window from ~1h to ~2s. Timer stays as the
hourly catch-all for the machine tiers.
Documents the 16:46 layout loss (uncommitted GUI state stashed, stash
entry destroyed during trunk sync) and the git-fsck recovery landed in
c87b378. Lesson codified in managed skills.
The rich GUI-built layout (cat/clock/clock-utc/weather start, taskbar
center, capsule groups g1-g4 + control-cheat-sheet end, thickness 36,
font_scale 1.3, opacity 0.9) existed only in the working tree; it was
stashed at 16:46 during the trunk merge and the stash entry was later
destroyed. Recovered from dangling stash commit 7fe3ed8 via git fsck.
This commit is the durable copy the layout never had before.
Uncommitted machine/session edits (live config, models, docs drift) were
blocking the merge of origin/main. Committed as-is to preserve them; the
merge that follows resolves overlapping prose files toward upstream
canonical, with local variants recoverable from this commit. Pre-merge
copies also in .AGENTTRASH/pre-merge-2026-10-18/.
First dogfooding round stamped the build worktree instead of the session's
own working directory (the value the paired session id resolves to). Rule
now says so explicitly. Refs #11
Every agent-opened issue/PR body ends with cwd + omp session id so machine
filed artifacts trace back to the box and session that produced them - the
live-sync daemon and filing agents make 'who/what wrote this' a real
question now. Mirrored in dank/serverAppConfigs by its own PR.
Refs #11
Operator decision at review: 15 min is aggressive for config churn; hourly
keeps the stale-window acceptable (<=1 h) with a fifth of the wakeups.
Timer unit, tier law, and failure-table wording aligned.
Frank
dank