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 `curl`s 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.