diff --git a/SKILLS.md b/SKILLS.md new file mode 100644 index 0000000..0eef819 --- /dev/null +++ b/SKILLS.md @@ -0,0 +1,85 @@ +# 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//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//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). No belt evidence yet. + +| Skill | Belt | Upstream @ ref → tree | Ver | Writes | Watch | +|---|---|---|---|---|---| +| brag-slim | ⬜ | latent-spaces/brag@069432c → e87c5bb | — | `brag-output/` | Built for Opus 5.5; 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/.json`, `.log` | Loop-owned state; no PII in state or logs | + +## Belts +| 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 a named seat, beat noise (10–20 prompts incl. near-misses, ≥3 trials each). Record the seat. 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; keep the ledger line. | + +Katas live in `.agents/katas//` (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//`); 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/` symlinks to `.agents/skills/`. +- 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 the result into the Belt column, with the seat. +- Time reads routes: an issue labelled `route:` gets that route's skills inlined into the seat's prompt.