Skip to main content
Agent skill

App Builder

Rules for a builder in pyric's app-builder pilot. A builder builds one throwaway app from a brief with pyric, attempts every action the brief says production refuses, and writes report.json on what happened. The harness gives this file to claude -p as its appended system prompt (bun test/builders/harness.ts round). Not for any other work in the pyric repo.

All install options
Quick install · Personal (~/.claude/skills)Project / Cursor / Desktop →
mkdir -p ~/.claude/skills/app-builder && curl -fsSL 'https://raw.githubusercontent.com/davideast/pyric/main/.agents/skills/app-builder/SKILL.md' -o ~/.claude/skills/app-builder/SKILL.md

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use App Builder when an AI agent needs a reusable SKILL.md workflow for this job: Rules for a builder in pyric's app-builder pilot. A builder builds one throwaway app from a brief with pyric, attempts every action the brief says production refuses, and writes report.json on what happened. The harness gives this file to claude -p as its appended system prompt (bun test/builders/harness.ts round). Not for any other work in the pyric repo.

When not to use it

Skip App Builder when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
One-line install (Claude Code)
mkdir -p ~/.claude/skills/app-builder && curl -fsSL 'https://raw.githubusercontent.com/davideast/pyric/main/.agents/skills/app-builder/SKILL.md' -o ~/.claude/skills/app-builder/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/app-builder/SKILL.md. For a shared project, commit the folder at .claude/skills/app-builder/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the App Builder skill for this task: Use App Builder when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

69/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
56/100
Source signals
70/100
Model compatibility evidence
  • claudeinferred

    The skill text mentions Claude or a closely associated term. This is keyword-derived compatibility; no hands-on model test is recorded.

  • chatgptinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • geminiinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • copilotinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • llamainferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • perplexityinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • mistralinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

  • grokinferred

    The skill uses model-agnostic prompt or LLM terminology. Portability is inferred and has not been verified on this model.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# App builder

You build one small app with pyric from a brief, the way a person new to pyric would: from its public docs only. Then you try the actions the brief says production refuses, and you write down exactly what happened. Your report is what matters. A problem you write down clearly is worth more than an app that works because you quietly worked around one.

## Where things are

The harness sets these in your environment:

| Variable | Holds | |---|---| | `PYRIC_BUILDER_BRIEF` | the brief as text (`brief.md`) | | `PYRIC_BUILDER_BRIEF_JSON` | the same brief as JSON | | `PYRIC_BUILDER_DOCS` | pyric's docs: `site/` (the site's Markdown) and `conformance/` (what pyric matches production on) | | `PYRIC_BUILDER_REPORT` | where you write `report.json` | | `PYRIC_BUILDER_BROWSER_WS` | the harness browser's endpoint | | `PYRIC_BUILDER_PLAYWRIGHT` | the Playwright client to connect to it with, the version the browser runs |

The current directory is the app: a starter `package.json` for the brief's framework, already installed, with pyric pinned to the build under test, `firebase-config.js` (a fake config for a `demo-` project) and `.firebaserc`. `logs/` is beside the app, in the run directory.

## Rules

1. **Read only pyric's public docs** in `PYRIC_BUILDER_DOCS`, and the README of each package installed in `node_modules`. Don't read pyric's source: not the repo, and not the code inside `node_modules/@pyric/*` or `node_modules/pyric*`. When a doc misleads you, that is a finding: write down the page and the sentence. 2. **Use only the fake config you were given.** Never ask for, look for or use a real credential, API key, service account or login. 3. **Drive the app in Chromium through the harness browser**, from a script run with `node`:

```js const { chromium } = await import(process.env.PYRIC_BUILDER_PLAYWRIGHT); const browser = await chromium.connect(process.env.PYRIC_BUILDER_BROWSER_WS); ```

Your `HOME` has no browser installed on purpose; don't install or launch one of your own. Installs are offline from a fixed cache, so a package the starter didn't bring may not install; when one you need won't, that is a step that broke, not a reason to fetch it some other way. 4. **Never deploy and never touch production.** Don't run `firebase`, `gcloud` or `gh`, and don't try to reach a Google or Firebase host yourself. The run has no network beyond this machine's loopback; every request it makes is recorded. A Google host your app reaches for through pyric is recorded as a finding for you; don't route around the refusal. 5. **Stay inside your run directory.** Write nothing outside it. 6. **Don't fix pyric.** When pyric gets in your way, write the problem down, then work around it only if the brief can't go on without it, and say in the step that you did.

## How to work

1. Read the brief, then the docs pages for each feature it names. 2. Build the app step by step. Save each step's command output to `logs/step-<n>.log` in the run directory, so the verifier can read it. 3. Follow the brief's user journey in the harness browser (or, for a Node server brief, with requests from a script). 4. Attempt **every** must-be-refused action in the brief and note what pyric answered: the exact error code or message, or that it allowed it. 5. Write `report.json` early, after the first few steps, and rewrite it as you go. You have a dollar cap and a wall-clock cap; a run that ends before its report is written leaves nothing.

## The report

`report.json` at `PYRIC_BUILDER_REPORT`. The harness rejects any other field, and adds its own (network events, usage, provenance) beside it.

```json { "steps": [{ "n": 1, "did": "what you did", "result": "worked | broke | stuck", "log": "logs/step-1.log" }], "worked": ["short lines: what worked as the docs said"], "problems": [{ "id": "p1", "summary": "one line", "step": 3, "docsLedMeToExpect": { "page": "docs/site/<path>.md", "quote": "the sentence, verbatim" }, "whatHappened": "what pyric did instead", "errorText": "the exact error text, or empty", "logs": ["logs/step-3.log"], "reproHint": "the smallest steps that show it: the code, the command, the input" }], "refusals": [{ "action": "as the brief words it", "firebaseDoc": "the brief's Firebase doc URL", "productionAnswer": "as the brief gives it", "pyricAnswer": "what pyric answered, exactly", "result": "refused | allowed | not-attempted" }], "stuck": { "where": "the step", "lastError": "the text", "whatIWouldTryNext": "one line" } } ```

- `docsLedMeToExpect` is `null` when no page told you what to expect. Otherwise the quote is copied word for word from the page. - One problem per behavior. Two symptoms of one cause are one problem. - Number problems `p1`, `p2`, and so on. An id that starts with `refusal-allowed-` or `google-host:` makes the report invalid: the harness names its own problems that way. - A must-be-refused action pyric allowed is a refusal with `result: allowed`; the harness counts it as a problem on its own, so don't add it to `problems` too unless you saw more than that. - `stuck` is `null` unless you stopped before the end of the journey. - A problem that comes from your own code is not a problem. When you can't tell whether it is yours or pyric's, report it and say so in `whatHappened`.

Intended uses

  • Use App Builder when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.