feat(caffeine-app): add skill for building a Caffeine app from scratch

[TomChantler]

Summary

Adds a new caffeine-app skill (category Integration) that teaches an agent the Caffeine app shape and the caffeine CLI build loop, so it can produce a buildable caffeine.ai app from nothing. It complements — and explicitly defers to — the existing motoko skill, which owns the Motoko language.

The skill covers:

• The project layout (pnpm workspace: root + src/backend Motoko canister + src/frontend React/Vite assets canister).
• All manifests inline and verbatim: the root caffeine.toml ([workspace]), the two canister caffeine.tomls, and the mops.toml for the single backend canister (toolchain pins, [canisters.backend.check-stable] with skipIfMissing, [moc] args).
• The build loop: pnpm install (first run) → caffeine install → build → check --fix → preview --build, plus the bindgen generation step and the fact that going live is a web-app action (no CLI deploy).
• A references/frontend-template.md with the full frontend boilerplate and a worked useActor(createActor) backend call.
• A Common Pitfalls section (the highest-value content) — 12 pitfalls, each backed by an eval.

It is aligned to the canonical build template (build-template-react): current toolchain pins, the @dfinity/* → @icp-sdk/* frontend migration, @caffeineai/core-infrastructure@^1.0.0, and the data-viewer MixinViews default — with a drift note, since the template manages and bumps these over time.

Why

The motoko skill teaches the language, not how a Caffeine project is laid out or built. An agent with only the motoko skill can write Motoko but cannot reliably produce a buildable Caffeine app from scratch. This skill is the missing greenfield piece, and it pairs with motoko (which it requires for backend code) and points to icp-cli for non-Caffeine IC/dfx work.

Validation

• npm run validate passes (skill-validator + project checks, 0 errors). One soft, non-blocking warning: the SKILL.md body is ~5.3k tokens vs the recommended < 5k — the content is intentionally dense (12 pitfalls + full inlined manifests).
• Verified end-to-end on @caffeineai/cli: a from-scratch app authored solely from this skill — a Motoko getCurrentTime query plus a frontend button that calls it via useActor(createActor) and displays the result — passes caffeine check --fix, compiles via caffeine build (backend.wasm + the bindgen-generated client + built frontend), and deploys a working draft via caffeine preview --build. Every greenfield gotcha that surfaced (the first-run --frozen-lockfile, check-stable skipIfMissing, preview needing a project id, build-before-check ordering, and what caffeine doctor actually installs) is documented as a pitfall and an eval.

Evaluation results

Totals: WITH-skill 54/55 output behaviours and 22/22 trigger classifications; WITHOUT skill 8/55.
(The single WITH partial is a brief-prompt nuance the skill states explicitly — run-to-run judge variance.)

  Output evals (WITH skill | WITHOUT skill):
    Root workspace manifest:                        WITH 4/4 | WITHOUT 1/4
    Backend canister manifest:                      WITH 4/4 | WITHOUT 0/4
    Frontend assets manifest:                       WITH 3/3 | WITHOUT 0/3
    mops.toml for the backend:                      WITH 5/5 | WITHOUT 0/5
    Backend canister must be named backend:         WITH 2/2 | WITHOUT 0/2
    Do not edit generated backend.ts:               WITH 2/2 | WITHOUT 0/2
    Build loop command sequence:                    WITH 4/4 | WITHOUT 1/4
    There is no caffeine init:                      WITH 3/3 | WITHOUT 0/3
    Deploy to a live URL:                           WITH 3/3 | WITHOUT 0/3
    Where Motoko goes and which skill:              WITH 2/2 | WITHOUT 1/2
    Frontend entry providers:                       WITH 3/3 | WITHOUT 2/3
    env.json purpose and build step:                WITH 2/2 | WITHOUT 0/2
    Project directory layout:                       WITH 3/3 | WITHOUT 0/3
    Missing generated bindings on a new project:    WITH 2/2 | WITHOUT 0/2
    Package manager is pnpm:                        WITH 1/2 | WITHOUT 0/2
    Frozen lockfile error on a fresh project:       WITH 3/3 | WITHOUT 2/3
    First check fails on missing backend.most:      WITH 2/2 | WITHOUT 0/2
    Preview needs a cloud project id:               WITH 2/2 | WITHOUT 0/2
    Calling a backend method from the frontend:     WITH 2/2 | WITHOUT 1/2
    Build before check (frontend imports backend):  WITH 2/2 | WITHOUT 0/2
  Trigger evals: should-trigger 14/14 | should-not-trigger 8/8

Notes for reviewers

• One skill per PR; no site edits needed (the site auto-discovers skills from frontmatter).
• All code/config blocks are reproduced from, and were exercised by, the end-to-end build above (through a successful caffeine preview --build draft).

[github-actions]

Skill Validation Report

Validating skill: /home/runner/work/icskills/icskills/skills/caffeine-app

Structure

• Pass: SKILL.md found
• Pass: internal link: references/frontend-template.md (exists)
• Pass: all files in references/ are referenced

Frontmatter

• Pass: name: "caffeine-app" (valid)
• Pass: description: (807 chars)
• Pass: license: "Apache-2.0"
• Pass: compatibility: (101 chars)
• Pass: metadata: (2 entries)

Tokens

• Warning: SKILL.md body is 5378 tokens (spec recommends < 5000)

Markdown

• Pass: no unclosed code fences found

Tokens

File	Tokens
SKILL.md body	5,378
references/frontend-template.md	5,245
Total	10,623

Content Analysis

Metric	Value
Word count	2,775
Code block ratio	0.26
Imperative ratio	0.14
Information density	0.20
Instruction specificity	1.00
Sections	19
List items	30
Code blocks	11

References Content Analysis

Metric	Value
Word count	1,801
Code block ratio	0.55
Imperative ratio	0.06
Information density	0.31
Instruction specificity	1.00
Sections	12
List items	7
Code blocks	14

Contamination Analysis

Metric	Value
Contamination level	low
Contamination score	0.09
Primary language category	config
Scope breadth	3

• Warning: Language mismatch: shell (1 category differ from primary)

References Contamination Analysis

Metric	Value
Contamination level	low
Contamination score	0.14
Primary language category	javascript
Scope breadth	3

• Warning: Language mismatch: config, markup (2 categories differ from primary)

Result: 1 warning

Project Checks

✓ Project checks passed for 1 skills (0 warnings)

[TomChantler]

Related Linear issue: https://linear.app/caffeinelabs/issue/SP-66/create-an-agent-skill-for-building-a-caffeine-app-from-scratch-host-on