Skip to content

feat(skills): drop the browser, web-search, and notify skills in favor of the zipbox catalog - #109

Merged
hishboy merged 5 commits into
mainfrom
chore/drop-redundant-skills
Aug 19, 2026
Merged

hishboy merged 5 commits into
mainfrom
chore/drop-redundant-skills

Conversation

@hishboy

@hishboy hishboy commented Aug 18, 2026 •

Copy link
Copy Markdown
Contributor

What

The product owner asked whether this harness ships browser, websearch, or other skills the zipbox catalog already covers, and to remove what it does. It shipped three.

Removed (doc only, 3 skills):

Skill Why
skills/browser zipbox-browser is a strict superset — same @playwright/cli, same pwcli env wrapper, same headless-only and session rules, plus generate-locator, network mocking (route/unroute/network-state-set), and modal-state error guidance this copy lacked.
skills/web-search Identical backend on both sides: src/helpers/WebSearch.ts POSTs /agent/web/search and /agent/web/extract, exactly what zipbox-websearch calls.
skills/notify zipbox-notify routes trading boxes straight back here: "on a trading-harness / ATA box, tribes-cli notify is that harness's own CLI — use it and stop."

Kept, deliberately: the tribes-cli web-search and tribes-cli notify command groups (src/cli/WebSearch.ts, src/cli/Notify.ts, both still composed in src/cli/Tribes.ts), the session_shutdown auto-notify Pi extension, and AGENTS.md's "Notifying the user" section. Only the skill docs go. news and tribes-login stay — no zipbox equivalent exists. A sweep of every remaining local skill found no further overlap (wallet-analyst reads third-party wallets; zipbox-wallet drives this box's own).

browser's only non-redundant content was its finance routing ("never scrape news sites here", "market data goes to the analyst skill"). That moved into AGENTS.md's External-info precedence bullet, where it now governs every browser route rather than one skill's readers.

Known partial regression — documented, not papered over

zipbox-websearch authenticates with tribes-agent-token, baked into zipbox sandboxes only. Outside a sandbox (Claude Code, Cursor, a local shell — all supported per AGENTS.md's Installation section) that wrapper has no credential. tribes-cli web-search keeps working everywhere after tribes-cli login, so it is now documented as the non-sandbox path in the AGENTS.md precedence bullet and in the Related-skills bullets of news, research-analyst, and commodity-analyst. That documentation is the mitigation.

Sync repoint — a hard dependency, not scope creep

skills/.synced.json pinned terminal 41865ee with 7 skills. bun run skills:upgrade resolves the current published release (contentSha256 1e741e4, terminal commit 0ab39f0f) and vendors 12: the 7 refreshed plus zipbox-api-keys, zipbox-desktop, zipbox-geo, zipbox-image, zipbox-notify. zipbox-email's copy now documents --body-html / --body-html-file (with a derived text/plain alternative), --cc (repeatable, 50 addresses), and --attach (10 files, 5 MiB caps) — verified by grep in the vendored file, not assumed.

It is a dependency of the removal: SkillsContract fails on any reference to a skill that is not on disk, so the escalation references cannot move to zipbox-notify until zipbox-notify exists here. It is also live in production — scripts/install-shared-skills.sh derives the sandbox runtime catalog from .synced.json, which was 7 stale skills and 5 missing.

Nothing here repoints the sync channel: #107 already replaced the archived ai-harness-setup codeload fetch with the content-addressed, digest-verified R2 channel. The plan on this branch predates that merge and calls for a gh api tarball fetch; it is obsolete and no such change was made.

Two fixes this branch had to absorb

1. main was red before this branch touched anything

159d89b installed skills/i-have-adhd/ with no allowed-tools frontmatter key, no routing-map row, and unformatted — three CI failures (run 31895271040). Repaired in commit #1 (9dadba8), which sits directly on origin/main and is cherry-pickable on its own if anyone wants main green sooner without the skills work. It is 2 files / 3 insertions: the frontmatter key, one routing-table row, prettier on that file. No test weakened, no other skill touched.

Evidence that it is a real repair and not a mask — format:check and bunx vitest run tests/skills/, by exit status, at three points:

Point format:check vitest tests/skills
(a) clean origin/main 1 1 2 failed / 146 passed, both in SkillsContract
(b) after commit #1 alone 0 0 148 passed — main-green restored by that commit by itself
(c) end of this PR 0 0 165 passed

2. The line cap was unsatisfiable by construction

MAX_LINES is unchanged at 300. What changed is which lines are counted.

scripts/skills-upgrade.mjs stamps a provenance marker after each vendored H1 and bun run format pads it with a blank line, so a vendored doc measures 2 lines longer than the file upstream wrote. Upstream enforces the same 300-line cap on the authored file, so the two caps measure different artifacts and any upstream doc spending its full budget could never satisfy this repo's. zipbox-image is 299 authored / 301 vendored and went red on arrival. The count now excludes the two injected lines.

Cross-repo coupling — this rots silently if unattended. tribes-protocol/terminal enforces 300 on the file its authors write (harnesses/setup/test/skills-contract.test.sh:91). This repo receives authored + 2: one marker line (H1_MARKER in scripts/skills-upgrade.mjs) plus one blank that prettier inserts. If terminal changes the marker text, or the vendor step starts injecting another line, the exclusion in tests/skills/SkillsContract.test.ts must change to match. The authored line count cases below fail if it does not — that is the alarm, and it is deliberate.

Raising the cap to 302 instead would have made zipbox-image pass and let a genuinely 302-line doc through. Excluding the marker does not. Four committed authored line count cases pin that difference so the "simplification" fails a test rather than quietly buying 2 lines of slack. Mutation-verified, not just run once: deleting the exclusion fails 3 of them, and replacing it with MAX_LINES = 302 fails the same 3.

Cross-reference rewrite

Rule applied throughout: a skill pointer becomes the zipbox slug; a tribes-cli command mention stays verbatim. A dangling pointer to a deleted skill actively misroutes the agent — worse than the redundancy this removes.

Rewritten across AGENTS.md (precedence bullet + 3 routing rows), skills/news, skills/research-analyst, skills/commodity-analyst, skills/prediction, .agents/desk-news.md, and docs/qa/p25-shared-skills-inheritance.md. That includes the four contract-enforced description (use …) refs — among them prediction's, which is folded across YAML lines 9–10 and which a plain grep does not find; it was caught by parsing frontmatter the way SkillsContract does.

Evidence

SkillsContract was driven red on purpose at the deletion step, before any rewrite — 5 failing assertions:

FAIL commodity-analyst > cross-references only skills that exist
     Related skills references unknown: web-search
FAIL news            > cross-references only skills that exist
FAIL prediction      > cross-references only skills that exist
FAIL research-analyst > cross-references only skills that exist
     description references unknown skill: web-search
FAIL AGENTS.md routing map > routes only to skills that exist
     routing map references unknown skill: web-search
Tests  5 failed | 137 passed (142)

Reproduced on the final history (3417b44 + the three git rms): same 5 assertions, 5 failed | 141 passed (146). After the rewrite: 165 passed (165), exit 0.

Gates, judged by exit status:

Gate Exit
bun run format:check 0
bun run lint 0
bun run build 0
bunx vitest run 0 — 450 passed (35 files)
bun run test:skills-release 0

test/shared-skills-install.test.sh runs as root in CI and derives its expectations from .synced.json (test/shared-skills-install.test.sh:13), so the 12-skill manifest needs no edit there; not run locally.

Blast radius re-verified after the edits: .pi/settings.json, bootstrap.sh, package.json, knip.jsonc, src/, tests/, scripts/, .agents/, .pi/ reference the three names only as new Command('notify') and new Command('web-search') — the two CLI groups that stay.

Follow-up needed on trading-org

The org layer (docs/org/ORGANIZATION.md, .agents/eng-* and pm-*, and 14 org-/eng-/exec-/portfolio- skills) lives on origin/trading-org, which has not merged to main. It carries 69 backticked references to the three deleted slugs across 25 files that do not exist on this base. They are untouched by this PR and will need the same sweep before or during that branch's merge, or SkillsContract goes red on it.

Not done

  • The web-search / notify CLI command groups stay — they are the capability layer, and the zipbox docs defer to them.
  • No vendored zipbox-* file was hand-edited (SyncedSkills.test.ts hashes every one; fix upstream in tribes-protocol/terminal).
  • Historical records under plans/ are left as written.

@hishboy
hishboy force-pushed the chore/drop-redundant-skills branch from 6e4b678 to 74b74d6 Compare August 18, 2026 23:30
@hishboy
hishboy changed the base branch from trading-org to main August 18, 2026 23:30
@hishboy hishboy changed the title PLAN: drop the browser, web-search, and notify skills in favor of the zipbox catalog feat(skills): drop the browser, web-search, and notify skills in favor of the zipbox catalog Aug 18, 2026
hishboy and others added 4 commits August 18, 2026 16:44
…and a routing row

159d89b installed skills/i-have-adhd/ by hand and left main red (CI run
31895271040). Three inherited failures, none related to the skill removal this
branch carries, but all of them block this PR:

- SkillsContract frontmatter assertion: the doc has no `allowed-tools` key, and
  the contract requires exactly `bash read` on every skill.
- SkillsContract "routes only to skills that exist": every slug except
  `tribes-login` must appear in the AGENTS.md routing map; this one did not.
- `format:check` exited 1 on the same file.

Fixed at the cause: add the frontmatter key, add one routing-table row, and let
prettier rewrap the doc. No test was touched.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…skills in favor of the zipbox catalog

Investigation-backed plan: capability comparison per candidate, a redundancy
sweep of all 68 skills, the full cross-reference rewrite map, the sync-channel
repoint (archived ai-harness-setup -> terminal harnesses/setup), contract-test
fail-first expectations, and blast radius.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
… 12 skills

The pin was terminal 41865ee with 7 skills. `bun run skills:upgrade` resolves
the current published release (contentSha256 1e741e4, terminal commit 0ab39f0f)
and vendors 12: the 7 refreshed plus zipbox-api-keys, zipbox-desktop,
zipbox-geo, zipbox-image, and zipbox-notify. zipbox-email's copy now documents
--body-html/--body-html-file, --cc, and --attach — that upstream fix rides along.

The sync is a hard dependency of the skill removal on this branch: SkillsContract
fails on any reference to a skill that is not on disk, so the escalation
references cannot move to zipbox-notify until zipbox-notify exists here. It is
also live in production — scripts/install-shared-skills.sh derives the sandbox
runtime catalog from skills/.synced.json, which was 7 stale skills and 5 missing.

Nothing here repoints the sync channel: #107 already replaced the archived
codeload fetch with the content-addressed, digest-verified R2 channel.

THE LINE CAP IS NOT RAISED. MAX_LINES is still 300. What changed is WHICH lines
are counted.

scripts/skills-upgrade.mjs stamps a provenance marker after each vendored H1 and
`bun run format` pads it with a blank line, so a vendored doc measures 2 lines
longer than the file upstream wrote. Upstream enforces the SAME 300-line cap
(harnesses/setup/test/skills-contract.test.sh:91) on the authored file — so the
two caps measure different artifacts, and any upstream doc that spends its full
budget was unsatisfiable here by construction. zipbox-image is 299 authored, 301
vendored, and went red on arrival. The count now excludes the two injected lines.

Raising the cap to 302 would have made the same doc pass while also letting a
genuinely 302-line doc through; excluding the marker does not. The new
`authored line count` cases pin that difference, and they pin the cross-repo
coupling with it: if upstream changes the marker text, or the vendor step starts
injecting a third line, they go red instead of the cap drifting silently.
Verified by mutation — removing the exclusion fails 3 of them, and replacing it
with MAX_LINES = 302 fails the same 3.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
… the zipbox catalog

The product owner asked whether this harness ships browser, websearch, or other
skills the zipbox catalog already covers, and to remove what it does.

Removed, doc only:

- skills/browser — zipbox-browser is a strict superset: same @playwright/cli,
  same pwcli env wrapper, same headless-only and session rules, plus
  generate-locator, network mocking (route/unroute/network-state-set), and
  modal-state error guidance this copy lacked. The only thing it had that
  upstream does not is finance routing ("never scrape news here", "market data
  goes to the analyst skill"), which now lives in AGENTS.md's External-info
  precedence bullet where it governs every browser route, not just this one.
- skills/web-search — same backend on both sides: src/helpers/WebSearch.ts POSTs
  /agent/web/search and /agent/web/extract, which is exactly what
  zipbox-websearch calls. Same output, same limits.
- skills/notify — zipbox-notify itself routes trading boxes back here: "on a
  trading-harness / ATA box, tribes-cli notify is that harness's own CLI — use
  it and stop."

KEPT, deliberately: the `tribes-cli web-search` and `tribes-cli notify` command
groups (src/cli/WebSearch.ts, src/cli/Notify.ts, both still composed in
src/cli/Tribes.ts), the session_shutdown auto-notify Pi extension, and AGENTS.md's
"Notifying the user" section. Only the skill docs go. `news` and `tribes-login`
stay — no zipbox equivalent exists. A sweep of every remaining local skill found
no further overlap: wallet-analyst reads third-party wallets where zipbox-wallet
drives this box's own.

KNOWN PARTIAL REGRESSION, not papered over: zipbox-websearch authenticates with
tribes-agent-token, which is baked into zipbox sandboxes only. Outside a sandbox
(Claude Code, Cursor, a local shell — all supported per AGENTS.md's Installation
section) that wrapper has no credential. `tribes-cli web-search` keeps working
everywhere after `tribes-cli login`, so it is now documented as the non-sandbox
path in the AGENTS.md precedence bullet and in the Related-skills bullets of
news, research-analyst, and commodity-analyst. That documentation IS the
mitigation.

Every reference was repointed in the same commit — a dangling pointer to a
deleted skill misroutes the agent, which is worse than the redundancy removed.
The rule applied throughout: a skill POINTER becomes the zipbox slug, a
`tribes-cli` COMMAND mention stays verbatim. The two surviving bare `web-search`
mentions in research-analyst name subcommands, and the one that read ambiguously
is now spelled `tribes-cli web-search`.

Verified no code path referenced the three slugs: .pi/settings.json, bootstrap.sh,
package.json, knip.jsonc, src/, tests/, scripts/, .agents/ and .pi/ hit only
`new Command('notify')` and `new Command('web-search')`, the two CLI groups that
stay.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@hishboy
hishboy force-pushed the chore/drop-redundant-skills branch from 0d20c9e to 550ab5a Compare August 18, 2026 23:45
…back

The PR that dropped skills/browser documented only half of the regression it
created. `zipbox-websearch` losing its credential outside a Tribes sandbox was
called out, with `tribes-cli web-search` named as the mitigation. The browser
half was left undocumented, and unlike websearch it has no mitigation: there is
no `tribes-cli browser` command, so outside a sandbox the browser route is
simply gone.

That silence is worse than the missing capability. skills/zipbox-browser tells
the agent that a missing baked command means "the sandbox predates this runtime"
and to report a stale image. In a Claude Code / Cursor / local-shell run — which
AGENTS.md's Installation section explicitly supports — playwright-cli was never
baked in the first place, so an agent following the fallback chains in news,
commodity-analyst, or research-analyst would refuse to proceed AND report a false
stale-image diagnosis.

The caveat lands in the External-info precedence bullet, where the browser route
is stated, and is mirrored one clause deep into the three Related-skills bullets
whose fallback chains reach it. The vendored skills/zipbox-browser/SKILL.md is
untouched — it must stay byte-faithful to upstream or the sync contract breaks.

Also corrects a false claim in the docblock of the `authored line count` cases:
they build their fixtures from the test's own SYNC_MARKER, which shares no source
with H1_MARKER in scripts/skills-upgrade.mjs, so they stay green under marker
drift rather than going red. The real alarm is the per-skill cap check —
zipbox-image is 301 raw / 299 authored, so a marker mismatch makes the exclusion
miss and that skill reads 301 > 300. Comment only; the test logic is unchanged
and was already fail-loud.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@hishboy
hishboy merged commit 901a7e6 into main Aug 19, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant