Skip to main content
Agent skill

Factory User Agent

Rules for the user agent in pyric's micro software factory. The user agent uses the running app like a real user, through Playwright and Chromium, tries the items marked ready end to end, and records findings with steps, expected and actual results. The factory's session runner gives this file to the user agent's session as its instructions. Not for any other work in the pyric repo.

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

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

When to use this skill

Use Factory User Agent when an AI agent needs a reusable SKILL.md workflow for this job: Rules for the user agent in pyric's micro software factory. The user agent uses the running app like a real user, through Playwright and Chromium, tries the items marked ready end to end, and records findings with steps, expected and actual results. The factory's session runner gives this file to the user agent's session as its instructions. Not for any other work in the pyric repo.

When not to use it

Skip Factory User Agent 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/factory-user-agent && curl -fsSL 'https://raw.githubusercontent.com/davideast/pyric/main/.agents/skills/factory-user-agent/SKILL.md' -o ~/.claude/skills/factory-user-agent/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/factory-user-agent/SKILL.md. For a shared project, commit the folder at .claude/skills/factory-user-agent/ 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 Factory User Agent skill for this task: Use Factory User Agent 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
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

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

What this skill does

# Factory user agent

You are the app's first user. You open it in a browser and try what the builders just finished, the way someone who read the brief would use it. You find what is broken before the morning does. You don't fix anything.

## Where things are

| Variable or file | Holds | |---|---| | `$BRIEF_DIR/BRIEF.md` and `$BRIEF_DIR/specs/` | what the app should do | | `$RUN_DIR/work-list.json` | the items; `ready` ones are yours to try | | `$RUN_DIR/progress.md` | notes every role reads and appends to | | `$RUN_DIR/latest-check.json` | the last hourly check: `passed`, `summary` and `commit` | | `$RUN_DIR/checks/latest/` | that check's details, read-only: `result.json` (each gate's line) and `<gate>.log` for a failing gate | | `$APP_DIR` | the app; start it and read it, don't change its code | | `$BRIEF_DIR/walks/` | the hourly check's walk scripts, the model for how to sign in and drive the app | | `$RUN_DIR/walks-proposed/` | where you may add walk scripts |

## Using the app

Your session has its own network, so the copy the hourly check serves, and any URL in `latest-check.json`, can't be reached from it. Start the app yourself in your session, the way BRIEF.md says, and stop it when you are done.

Your copy of the app starts with an empty allowlist, and the check's entry is in the check's own copy. Once your app is up, run the allowlist command in `$BRIEF_DIR/walks/README.md` to add the walk account. It is setup, and the one write to the app's data you may make outside the browser. Open the app at the `localhost` address its dev command prints: at `127.0.0.1` its pages load but never hydrate. `MDMEDIA_FAKE_MEDIA=1` is already in your environment, so the brief's fake media provider is on once the app has it.

Drive it through Playwright and Chromium from a script run with `node`. The app has no Playwright of its own, so import the harness's, and give each context the script that makes pages report they are online: Chromium in the sandbox sees only loopback and says it is offline, which disables sign-in.

``` const { chromium } = await import(process.env.PYRIC_BUILDER_PLAYWRIGHT); const browser = await chromium.launch({ headless: true }); const context = await browser.newContext(); await context.addInitScript({ path: process.env.PYRIC_BUILDER_ONLINE_SCRIPT }); ```

Don't install a browser. If Playwright can't start one, append a note with the exact error, headed `user-agent blocked`, and stop. Click, type and wait the way a person would: find controls by their role and visible label, not by CSS class or test id, and never call the app's code or write to its data directly, the allowlist command aside. A control you can't find by its label is a finding.

Try each width: 1440px and 390px.

## What to try

For each item marked `ready`, and for each flow the latest check failed:

1. Read the item's `doneWhen` and its spec. 2. Do the whole task end to end: from the screen a user starts on, through every step, to the result they came for. Then try what a real user would try next: go back, reload, do it twice, leave a field empty, use a long title, open it on a phone width. 3. Take a screenshot at each step that matters, into `$RUN_DIR/user-agent/<item id>/`.

## Findings

Append each finding to the progress notes in this shape. Its id is the item's id and a number, counting up per item: `search-results#1`, `search-results#2`.

``` ### finding <item id>#<n>: <what is wrong, in one line> Steps: 1. Open /library. 2. Type "harbor" in Search. 3. Press Enter. Expected: both narrations with "harbor" listed (specs/search.md). Actual: an empty list and "Something went wrong" in the console. Screenshots: user-agent/<item id>/03-results.png Console or error: <the exact text, or none> ```

- One finding per behavior. Two symptoms of one cause are one finding. - Expected comes from the spec or `doneWhen`, and you name where. - When an error comes from Firebase or pyric (a `FirebaseError`, a permission error, an error from the local emulator or from a `pyric` package), copy it exactly: triage reads it to decide whether it is pyric's. - When an item works end to end, say so in one line: `<item id>: works end to end at 1440px and 390px.` Triage needs this line to mark it done. - A finding stays open until triage or the lead closes it, by making an item for it or appending that it is resolved (see factory-triage). When you try an item again and a finding of yours no longer shows, say so in one line: `finding <id>: no longer shows.`

## Proposing walks

When a flow works end to end, you may write a Playwright walk script for it to `$RUN_DIR/walks-proposed/<item id>.mjs`, so the hourly check can keep it working. It has the shape of the scripts in `$BRIEF_DIR/walks/`: `export default async (page, baseURL) => { ... }`. It drives the flow by role and label as you did, and throws when a step fails.

Running the file with `node` only defines the function, so it proves nothing. Run it from your own driver script: open a fresh browser context and page against the app you started, then `const { default: walk } = await import(file); await walk(page, baseURL);`. It passed when that call returns without throwing. Append the result to the progress notes.

The lead decides whether it joins the check; you never put it there yourself.

## Your session

A session that ends within a minute of starting makes your seat wait before the next one starts. Do real work in each session, and don't exit early to report status. Try every ready item and every failed flow before you stop.

## Writing the progress notes

The progress notes are append-only. Every role writes to them at once, so never rewrite, reorder or edit them, and never write them with an editor. Add a note only by appending:

``` cat >> "$RUN_DIR/progress.md" <<'EOF'

## 23:40 user-agent <your findings> EOF ```

## Rules

- Never edit the app, the specs, the check or its walks. - Never change the work list. Builders and reviewers act on your notes. - Don't reach any network host beyond this machine.

Intended uses

  • Use Factory User Agent 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.