teahub/SKILLS.md

SKILLS.md — Teahub

AGENTS.md says how to move here. DESIGN.md says what good looks like (still on the old instance until ported). This file says which procedure to run, where it came from, and how far it is trusted. Skills live in .agents/skills/<name>/SKILL.md.

 issue / loop ──route──▶ 1–3 skills, named by path ──▶ seat reads each SKILL.md and follows it ──▶ PR

 lifecycle:  proposed ──PR + lint──▶ ⬜ white ──katas beat no-skill──▶ 🟩 green ──grown from our traces──▶ ⬛ black
                                        │                                  │
                                        └─────────────▶ 💤 retired ◀───────┘   (a seat passes the katas without it)

Rules

1. Name skills by path. A route, an issue or a loop prompt says "read .agents/skills/<name>/SKILL.md and follow it". Never count on a harness noticing a skill: unaided, they fire about half the time. No model decides which skill to load.
2. One to three skills per task. Past three, gains shrink and look-alike skills shadow each other.
3. Skills are read-only at run time. Upstream changes arrive as a diff PR at a recorded ref; ours arrive as a PR with katas. No skill fetches its own updates.
4. Context files are shared memory. Read freely; change by PR. Loop state under .agents/loops/ is the one exception.
5. Untrusted text gets its own seat. Anything that reads the open web (listening, a site being filmed) runs with no secrets and no repo write, and hands off a digest.
6. A missing sibling is a signal. Vendored skills point at upstream siblings we don't carry (emails, cro, …). Do the task without it and name the gap on the issue; repeated gaps decide what we vendor next.

Harnesses: Codex, VS Code, Gemini CLI, OpenCode and goose read .agents/skills/ natively. Claude Code reads .claude/skills/ only (and follows symlinks there). Time's seats are API calls (seats.json): they see a skill only when Time's prompt carries it.

Routes

Every marketing route reads .agents/product-marketing.md first; the skills do that themselves.

Route	Task	Load, in order	Constraints
context	Write or refresh a product's marketing context	product-marketing	Output is a PR to .agents/product-marketing.md
launch	Launch or release announcement	launch → copywriting
post	Bluesky post or thread	social
article	dev.to article or content plan	content-strategy → copywriting
listen	Social-listening digest	social (references/listening.md)	No secrets, no repo write; writes a digest
loop	Design a recurring marketing loop for Time	marketing-loops	The loop it designs runs one of these routes
video	Launch video for a project or site	brag-slim	Astra (Opus 5.5) only; no secrets; keep brag-output/ out of git

Ledger

All seven admitted 2026-10-14 by manual scan (no hidden Unicode, no HTML comments, no install or update steps, no allowed-tools); CI lint pending. Upstream tree = the skill's folder upstream at that ref, evals/ included (we keep evals out of the skill folder). Belts are per seat (Luna · Sol · Astra); no evidence yet.

Skill	Belts L·S·A	Upstream @ ref → tree	Ver	Writes	Watch
brag-slim	— · — · ⬜	latent-spaces/brag@069432c → e87c5bb	—	brag-output/	Built for Opus 5.5 (Astra only); headless browser + render; downloads the target site's assets
product-marketing	⬜ ⬜ ⬜	coreyhaines31/marketingskills@c7d7dfb → 1bca9cf	2.1.0	.agents/product-marketing.md	The one product-truth file; don't start a second (e.g. PRODUCT.md)
launch	⬜ ⬜ ⬜	marketingskills@c7d7dfb → adfac43	2.2.0	—	Points at unvendored cro, emails, popups, signup, onboarding, video
social	⬜ ⬜ ⬜	marketingskills@c7d7dfb → 2bde174	2.3.4	.agents/listening-sources.md (setup)	Listening curls Reddit, HN, Bluesky, YouTube: untrusted text (route listen)
content-strategy	⬜ ⬜ ⬜	marketingskills@c7d7dfb → 874a880	2.1.3	—	Points at unvendored seo-audit, ai-seo, programmatic-seo, site-architecture
copywriting	⬜ ⬜ ⬜	marketingskills@c7d7dfb → 08b81e8	2.2.0	—	Hands email and popup copy to unvendored emails, popups
marketing-loops	⬜ ⬜ ⬜	marketingskills@c7d7dfb → 8685f11	1.4.0	.agents/loops/<loop>.json, .log	Loop-owned state; no PII in state or logs

Belts

A belt is a badge, awarded to one seat for one skill: a skill can be 🟩 on Luna and ⬜ on Astra. Once seats have lineage identities, belts are issued as badges to the seat's npub (docs/lineage.md); until then, they live in the ledger above.

Belt	Means	Gate
⬜ white	admitted	Every file read. Lint clean: no hidden Unicode or HTML comments, no fetch-and-run, no allowed-tools, no !`cmd` lines, no binaries. Upstream ref and tree in the ledger. A line in docs/decisions.md.
🟩 green	earns its keep	Its katas, run with and without it on that seat, beat noise (10–20 prompts incl. near-misses, ≥3 trials each). Green on Luna is worth more than green on Astra: a skill that lets a cheaper seat do the job is a cost lever.
⬛ black	ours	Grown or specialised from the factory's own traces; beats the current version on held-out katas; reviewed by a seat from another model family. Never merged by the seat that wrote it.
💤 retired	absorbed	The seat passes the skill's katas without it. Drop the route for that seat; keep the ledger line.

Katas live in .agents/katas/<skill>/ (CI-only; seats never load them). Upstream evals/evals.json files are the seed katas. The dojo grades seats with katas, and the same katas grade skills: seat × skill is one matrix — rows rank seats, column deltas rank skills.

Moves

• Add: read every file; copy the folder (its evals/ → .agents/katas/<skill>/); add a ledger line, a route, and a line in docs/decisions.md. One PR.
• Update: re-vendor at a newer upstream ref as a diff PR; update the ledger line.
• Propose: any seat or loop may open a PR with a new or edited skill plus its katas.
• Human gate: a diff that adds network calls, scripts, binaries or tool grants goes to the owner (teahubxyz). Everything else merges on green checks.

Not automated yet

• Claude Code view: generated .claude/skills/<name> symlinks to .agents/skills/<name>.
• CI lint on .agents/**: the white-belt checks.
• Weekly upstream diff: per ledger line, fetch upstream and open a PR when the tree or version moves.
• Kata runner: with/without runs per skill per seat; writes each seat's belt into the ledger (badges, once seats have lineage identities).
• Time reads routes: an issue labelled route:<name> gets that route's skills inlined into the seat's prompt.