SKILLS.md: routes, ledger and belts for skills (#7)
The third root file next to AGENTS.md and DESIGN.md. Routes name 1–3 skills by path per task; the ledger records upstream ref + tree, version and what each skill writes; belts gate trust on evidence. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01H4upF5LVwmPDDqrhdUfnXh
This commit is contained in:
teahubxyzandClaude Opus 5.5 committed
1 parent
ca281d8d8d
commit
6c554ae4b8
1 file changed
+85
@@ -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/<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). 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/<loop>.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/<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 the result into the Belt column, with the seat.
|
||||
- Time reads routes: an issue labelled `route:<name>` gets that route's skills inlined into the seat's prompt.
|
||||
Reference in new issue
Block a user