Teach generate_repo_pointer_skill that a repo carries a banner and what binds its description #1080

New issue

Open

opened 2026-08-16 01:11:50 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-16 01:11:50 +00:00

Member

Problem

A repo's GitHub description is sometimes design type, and nothing tells an agent editing it. generate_repo_pointer_skill turns that description into repo-<name>/SKILL.md, which is the surface agents actually load, so it is the natural place to carry the constraint.

Concrete failure this came from: a content review proposed replacing agent-compose's description with a 64-char line. That description is the tagline on assets/banner/agent-compose-banner.jpg, and the replacement measured 1.27 times the heading width, inverting a lockup whose design rule is that the tagline stays narrower than the name. Nothing in the loaded context connected "GitHub description" to "banner type", and no skill would have fired on that phrasing.

What the two shipped banners establish

Measured in the shipped font stack (Avenir Next, Demi for heading, Regular for tagline, sizes as fractions of a 1280 base):

agent-compose - heading agent-compose // $ acompose 709px, tagline Eval driven agent roles and personas 520px, ratio 0.73, ceiling near 42 chars.
sirens-echo - heading sirens-echo // sirens-deep 596px, tagline a discord community agent harness 502px, ratio 0.84, ceiling near 33 chars.

These reproduce the figures already recorded in agentic-os-xxx scripts/banners/sirens_banner.py, which notes sirens-echo "sits at 0.84" and that a short name puts the tagline "at 1.46". So the ratio is an established design concept, not something invented here.

Three consequences for any generated note:

The ceiling is per-product, not a constant. 42 chars for one repo, 33 for the other. It falls out of the heading string and heading size, so the generator must not hardcode a number.
Shortening the tagline is not the only lever. When Sirens // Discord measured 1.46, Designer enlarged the heading from 50 to 81 rather than cutting words. A note that says "keep it under N chars" would teach the wrong fix.
The description is not the tagline. It opens with it. sirens-echo ships tagline a discord community agent harness and description A discord community agent harness - home of sirens echo and sirens deep. agent-compose is the degenerate case where the extension is empty, which is what made them look identical.

That third point is the useful rule: the banner constrains the opening of the description, and the remainder is free prose. A repo can carry reader payload past the tagline without touching the art.

Proposed change

When generating a pointer for a repo that carries a banner, emit a short block saying so. Suggested content:

this repo ships a banner, and its tagline is the opening of this description
changing that opening means reminting the art, which is Designer plus agentic-os-xxx
the remainder of the description is free
pointer to the product repo's own banner doc for the settled numbers

Detection has a wrinkle. The two repos disagree on where banners live:

agent-compose - assets/banner/agent-compose-banner.jpg, one file
sirens-echo - assets/banner.jpg, banner-2x.jpg, banner-no-logo.jpg, banner-no-logo-2x.jpg

So either the glob covers both shapes, or the asset path gets settled first. Worth deciding before writing the detector.

What stays out of scope

The generator lives here and must not reach into agentic-os-xxx for font metrics or heading strings. Those are private and belong to the layer that owns the art. The generator should assert only what it can read from the product repo it is generating for: that a banner exists, and where that repo documents it. The numeric ceiling stays with the product, in files like agent-compose/docs/compose-banner.md.

If a machine-readable ceiling is wanted later, the right shape is a declaration in the product repo, since that is the lowest layer that fully determines it.

coilyco-flight-deck/agent-compose#284 - the description this surfaced through
coilyco-bridge/agentic-os-kai#875 - stale pointers, same generator, adjacent failure mode
agentic-os-xxx docs/features-banners.md, banner-system.md, and the kai-comfyui-agentic skill that owns the banner craft

## Problem A repo's GitHub description is sometimes design type, and nothing tells an agent editing it. `generate_repo_pointer_skill` turns that description into `repo-<name>/SKILL.md`, which is the surface agents actually load, so it is the natural place to carry the constraint. Concrete failure this came from: a content review proposed replacing agent-compose's description with a 64-char line. That description is the tagline on `assets/banner/agent-compose-banner.jpg`, and the replacement measured 1.27 times the heading width, inverting a lockup whose design rule is that the tagline stays narrower than the name. Nothing in the loaded context connected "GitHub description" to "banner type", and no skill would have fired on that phrasing. ## What the two shipped banners establish Measured in the shipped font stack (Avenir Next, Demi for heading, Regular for tagline, sizes as fractions of a 1280 base): * **agent-compose** - heading `agent-compose // $ acompose` 709px, tagline `Eval driven agent roles and personas` 520px, ratio **0.73**, ceiling near 42 chars. * **sirens-echo** - heading `sirens-echo // sirens-deep` 596px, tagline `a discord community agent harness` 502px, ratio **0.84**, ceiling near 33 chars. These reproduce the figures already recorded in `agentic-os-xxx` `scripts/banners/sirens_banner.py`, which notes sirens-echo "sits at 0.84" and that a short name puts the tagline "at 1.46". So the ratio is an established design concept, not something invented here. Three consequences for any generated note: 1. **The ceiling is per-product, not a constant.** 42 chars for one repo, 33 for the other. It falls out of the heading string and heading size, so the generator must not hardcode a number. 2. **Shortening the tagline is not the only lever.** When `Sirens // Discord` measured 1.46, Designer enlarged the heading from 50 to 81 rather than cutting words. A note that says "keep it under N chars" would teach the wrong fix. 3. **The description is not the tagline.** It opens with it. sirens-echo ships tagline `a discord community agent harness` and description `A discord community agent harness - home of sirens echo and sirens deep`. agent-compose is the degenerate case where the extension is empty, which is what made them look identical. That third point is the useful rule: **the banner constrains the opening of the description, and the remainder is free prose.** A repo can carry reader payload past the tagline without touching the art. ## Proposed change When generating a pointer for a repo that carries a banner, emit a short block saying so. Suggested content: * this repo ships a banner, and its tagline is the opening of this description * changing that opening means reminting the art, which is Designer plus `agentic-os-xxx` * the remainder of the description is free * pointer to the product repo's own banner doc for the settled numbers Detection has a wrinkle. The two repos disagree on where banners live: * `agent-compose` - `assets/banner/agent-compose-banner.jpg`, one file * `sirens-echo` - `assets/banner.jpg`, `banner-2x.jpg`, `banner-no-logo.jpg`, `banner-no-logo-2x.jpg` So either the glob covers both shapes, or the asset path gets settled first. Worth deciding before writing the detector. ## What stays out of scope The generator lives here and must not reach into `agentic-os-xxx` for font metrics or heading strings. Those are private and belong to the layer that owns the art. The generator should assert only what it can read from the product repo it is generating for: that a banner exists, and where that repo documents it. The numeric ceiling stays with the product, in files like `agent-compose/docs/compose-banner.md`. If a machine-readable ceiling is wanted later, the right shape is a declaration in the product repo, since that is the lowest layer that fully determines it. ## Related * coilyco-flight-deck/agent-compose#284 - the description this surfaced through * coilyco-bridge/agentic-os-kai#875 - stale pointers, same generator, adjacent failure mode * `agentic-os-xxx` `docs/features-banners.md`, `banner-system.md`, and the `kai-comfyui-agentic` skill that owns the banner craft

coilyco-ops added the

labels

2026-08-17 02:36:59 +00:00