# Instructions and skills

The instructions shape every run. Skills carry the detail the model loads only when it applies. Taste goes into artifacts the gate can check, never adjectives.

## Instructions

`instructions` names one package-relative Markdown file. Aim for 4 to 9 KB. Shorter usually means the package has no opinion; longer usually means a skill's material leaked in.

### The test for every line

A line earns its place if it changes what the model does, or names a failure that has actually happened. Delete anything a capable model already does, anything that restates the manifest, and every hedge: "consider", "where appropriate", "try to", "best practices", "as needed".

### Structure

1. **Role and environment.** One paragraph: what the work is, how it is judged, and the hard facts of the runtime.
2. **Tools.** Every packaged command, what it does, and what its exit code means. The gate goes here, with the sentence that makes it the definition of done.
3. **Method.** The order of work and the first skill to load.
4. **Precedence.** What wins when sources conflict. Always: the user's stated scope beats every skill default.
5. **Invariants.** Rules that hold on every run, each stated once.
6. **Field rules.** Terse, specific failure knowledge, grouped by area.
7. **Done means.** A checklist a reviewer could tick from evidence.
8. **Report.** What was built, what the gate reported, what the evidence shows, and what could not be verified, failures first.

### Examples

Role and environment:

> You build and upgrade browser games with Three.js. A run is judged on whether the game plays, how it looks in captured frames, and whether every control does what its visual says. The sandbox has no display and no GPU: rendering uses software WebGL, so frame rate is not evidence of anything.

Tools:

> `gate [dir]` builds the project, serves it, captures every viewport and state listed in `artifacts/evidence.json`, runs the checker, and exits non-zero on any failure. Exit 0 is the only definition of done.

Precedence, when the package adapts borrowed skills:

> You work alone: where a skill says to delegate, do the work yourself.

Invariants:

> - Playable first: the core loop works before any polish.
> - Never fake an acknowledgment to make a capture pass, and never drop a failing capture from the manifest.
> - Look before you judge. A claim about how the result looks cites a screenshot you opened.

Done means:

> - The gate exits 0 on the final run.
> - Every planned state has a capture you opened.
> - Data survives a relaunch.
> - Delete exists wherever create does.

### Field rules

The highest-value section, and the one generic advice can never write. Each rule is a failure that happened, stated as the fix:

> - Never `pkill -f` a server: the pattern matches your own shell and kills it. Use the stop command the serve tool printed.
> - Wait on conditions, never fixed frame counts or sleeps.
> - Every command runs from the workspace root with relative paths. Never use `..`; the permission checker resolves it against the root and ends the run.
> - Never wrap a user-triggered call in a silent `try?`: a failed request then looks exactly like a dead button.
> - Test every auth or storage change starting from state the previous build left behind, not only from a fresh session.
> - Measure latency from the input event to the rendered change, never from an internal variable.

Field rules name the canonical way and forbid the specific anti-pattern. The costliest failures come from a model hand-rolling something a reference implementation already solves, from tests that only cover fresh state, and from acceptance measured somewhere the user never looks.

Add a field rule every time a trial transcript shows the model losing time or quality to the same mistake twice. Say what the Workbench cannot do (no database tool, say) and what to do instead: build against an interface and a test fake, and report what it needs.

### Voice

Write as the senior practitioner who has shipped this work many times and is tired of watching it go wrong the same ways. Declarative sentences. One way of working, stated as the way.

### What the engine adds

You do not write the outbox rules. The engine gives every runner a short `<workbench_context>` block before your instructions, explaining that requested files go to `WORKBENCH_OUTPUT_DIR` and links go in `outcome.json`, and a `<workbench_runtime>` block with the actual workspace paths, access, and outbox. It adds no persona, tools, or permissions. See [Outcomes contract](/docs/standard/outcomes).

## Skills

Each `skills` entry is a package-relative directory with a portable `SKILL.md`. The runner exposes skills through its native on-demand mechanism, so a skill costs nothing until its description matches.

```text
.workbenches/
  game/
    workbench.yml
    instructions.md
    skills/
      game-workflow/
        SKILL.md
      look/
        SKILL.md
        references/rubric.md
      proof/
        SKILL.md
        scripts/gate.mjs
```

### The skill format

- A directory with a lowercase hyphenated name.
- `SKILL.md` with YAML frontmatter: a `name` matching the directory and a `description`.
- Every trigger condition goes in the description. The body is imperative.
- Detailed material goes in one-level-deep `references/` files linked from `SKILL.md`. Scripts and templates go in `scripts/` and `templates/` or `assets/`.
- No READMEs or changelogs inside a skill.

### Split by judging axis or phase

Give the work one entry point: a workflow skill, or a short method section in the instructions, that routes to the rest. Then one skill per judging axis or phase (`look`, `feel`, `work`, `proof`), each loaded when its description says it applies. Two competing entry skills is a defect.

Each skill holds the decisions to make before building, the standard to meet, the failures to avoid, and its templates and scripts. Ship templates for anything the model would otherwise hand-write badly: project scaffolds, test harnesses, config.

Adapt borrowed skills to this runtime instead of vendoring them verbatim. A skill that mentions tools or delegation the package does not have teaches the model to fail. Record the provenance of borrowed material in the package's NOTICE.

## Taste

Adjectives do not move a model. Replace "make it beautiful" with three artifacts.

### A design artifact

A file the model writes before any implementation, with required decisions. The gate checks that it exists and that its declared states match the evidence manifest. For an app:

1. **Concept**: anchored in something physical or cultural (a field notebook, a transit departure board), not a mood word.
2. **Palette**: named tokens with values and roles.
3. **Type**: families, scale, and where each is used.
4. **Shape**: corner radii, stroke weights, density.
5. **Signature element**: the one thing a screenshot is recognized by.
6. **Iconography and voice.**
7. **States**: a table of every screen and state the work must prove.

Then a rule that code uses tokens only: no raw colors, no ad hoc sizes.

### A rubric

A rubric turns "good" into something two reviewers would score the same way.

- **Categories** follow the judging axes.
- **A scale** with a concrete description of every level in every category: "0: unstyled primitives. 1: basic object with a glow. 2: authored silhouette, trim, and state cues. 3: reads as a finished asset at a glance."
- **Calibration anchors**: reference images or examples for low and high levels.
- **Thresholds**: "Done: every category at least 2 and the average at least 2.3."
- **Automatic failures**: patterns that fail the work regardless of score.
- **An anti-gaming rule**: adapt categories to the genre by naming the equivalents first; never add content just to raise a score.

### A blacklist of default taste

Generated work converges on recognizable templates. Name the ones this domain falls into, specifically enough that the model can recognize itself:

- A cream or parchment background with a terracotta accent and a serif headline.
- A centered hero, three feature cards, and a gradient button.
- Untextured primitives, empty arenas, and box skylines in a 3D scene.
- Placeholder copy, lorem ipsum, or "Replace this with your first screen".

Pair each with what to do instead, or point at the design artifact decision that prevents it.