Browser Automation with agent-browser

Use this skill to drive websites through the agent-browser CLI. Keep the main loop tight: inspect the page, act with refs, verify the result, and only pull deeper docs when the task actually needs them.

Core workflow

Prefer agent-browser directly for speed. Use npx agent-browser only if it is not installed globally.

For most tasks, follow this loop:

1. Open the page
2. Wait for the relevant state
3. Snapshot with refs
4. Interact using those refs
5. Re-snapshot after page or DOM changes
6. Verify the outcome
7. Close the session when done

agent-browser open https://example.com/form
agent-browser wait --load networkidle
agent-browser snapshot -i
# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"

agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i

Chain commands with && only when you do not need to inspect intermediate output. Good: open && wait && screenshot. Bad: snapshot && click when you still need to read the refs from the snapshot.

Route fast

Read only the reference that matches the task:

Golden path commands

Use these first; go to the command reference only when you need something more specific.

agent-browser open <url>
agent-browser wait --load networkidle
agent-browser snapshot -i
agent-browser click @e1
agent-browser fill @e2 "text"
agent-browser select @e3 "option"
agent-browser get url
agent-browser get text @e1
agent-browser diff snapshot
agent-browser screenshot --annotate
agent-browser close

Refs are the default interaction model

The main value of agent-browser is that snapshots produce compact refs like @e1, @e2, @e3. Those refs are cheaper and more reliable than repeatedly reasoning from raw HTML or long selectors.

Treat refs as short-lived. Re-snapshot after anything that can change the page state, especially:

• navigation
• form submission
• opening dropdowns or modals
• lazy-loaded or client-rendered content

If a ref fails or the page looks different from what you expected, your next move is usually agent-browser snapshot -i, not another blind click.

For the full lifecycle and troubleshooting rules, read references/snapshot-refs.md.

Choose the lightest tool that still proves the result

Default order:

1. snapshot -i for structure and interactive targets
2. get text, get url, or get title for precise verification
3. diff snapshot when you need to confirm something changed
4. screenshot --annotate when layout, icon-only controls, canvas, or visual context matters
5. semantic locators or eval only when refs are unavailable or the task truly needs them

If you need semantic locators, JavaScript evaluation, local file access, annotated screenshots, or config details, jump to references/advanced-usage.md and references/commands.md.

Authentication: decide sensitivity first

Before filling any credential, classify the auth flow.

• Non-sensitive: localhost, staging, test accounts, or credentials the user explicitly provided for this task. The agent can usually fill these directly.
• Sensitive: production domains, real user accounts, OAuth/SSO, or anything where the agent should not handle the secret. In that case, reach the auth step, switch to a headed browser if needed, and let the user complete sign-in manually.

After either path succeeds, offer to save reusable state if it would help next time. Do not auto-save credentials or session state without asking.

Use references/authentication.md for the exact decision rules and storage patterns.

Sessions: isolate work on purpose

Use named sessions when you are:

• running parallel browser tasks
• comparing two sites or variants
• preserving auth state for reuse
• avoiding interference across agents

When multiple agents may browse concurrently, use a named session from the start and close it explicitly when finished. Prefer semantic names over generic ones.

For session reuse and cleanup patterns, read references/session-management.md.

Security defaults for AI-driven browsing

If the page is untrusted or may contain hostile content, enable content boundaries before inspecting rich output. If the task is scoped to a known target, consider an allowlist for trusted domains.

The main point is to keep page content clearly separated from tool output and to narrow where the browser is allowed to go when the task permits it.

See references/advanced-usage.md for content boundaries, domain allowlists, action policy, and output limits.

Failure modes to catch early

• Stale refs: you interacted after the page changed without re-snapshotting
• Missing waits: you captured or clicked before async content settled
• Visual-only UI: text snapshots missed icon buttons, canvas, or spatial layout
• Shell quoting in eval: use the safer patterns from the advanced usage reference
• Leaked sessions: you forgot to close the browser session after finishing

For worked examples and reusable flows, use the scripts in templates/ and the deeper references instead of expanding the hub.

Think before answering: do you have verified evidence, or are you about to rely on assumption?

Verify Before You Answer

Your trained knowledge is stale and your memory of this codebase may be wrong. Verify from source before claiming anything:

• Question about specific code? → Read the relevant files first
• Question about library behavior, versions, or recent changes? → Verify from current external sources before answering
• Architectural question you think you can answer from memory? → Still check the actual codebase — confirm before claiming

Explain, don't implement

This skill ends at the explanation — the user decides what to do next. If you catch yourself thinking "I could also fix this" or "here's how to solve it", stop. Explain only.

This is not a coding session. No code blocks — not even to illustrate format or behavior. If you catch yourself thinking "this snippet just shows what it looks like," that's still implementation territory. Explain in prose.

Question

$ARGUMENTS

Ultrathink.

Mode Detection

Detect operating mode before anything else:

1. VERSION file exists in CWD → push mode (CWD is the prime repo)
2. .claude/.prime-version exists in CWD → pull mode (CWD is a target project)
3. Neither detected → ask user which mode and for the required path

Push Mode — Resolve Target

Source = CWD (prime repo). Target = resolved project path.

State file: .claude/prime-projects.json

Tracks known target paths, last sync time, and version. Shape:

{ "projects": [{ "path": "/absolute/path", "lastSynced": "2025-12-30T10:30:00Z", "version": "1.4.2" }] }

Create as { "projects": [] } if missing.

Resolution flow:

1. Argument provided → Use that path, then record it after a successful sync
2. No argument, known projects exist → Ask the user which project(s) to sync, including an All projects option
3. No argument, no known projects → Ask the user for a path

State file management:

• Create .claude/ only if you need to persist the state file
• Update the synced project's time/version only after a successful sync
• Keep one entry per absolute path

Pull Mode — Clone Prime

Source = cloned prime repo. Target = CWD.

Flow:

1. Read current version from .claude/.prime-version in CWD
2. Generate timestamp: date +%Y%m%d%H%M%S
3. Clone prime repo: git clone https://github.com/avibebuilder/claude-prime.git /tmp/claude-prime-sync-<timestamp>/
4. Set source = /tmp/claude-prime-sync-<timestamp>/, target = CWD
5. Continue to shared process below
6. Clean up /tmp/claude-prime-sync-<timestamp>/ after sync completes (success or failure)

No state file in pull mode — the target project is self-contained.

Process

1. Validate Target

• Check that the target path exists, is a directory, and is not the same location as the source repo
• Treat a valid target as a project root where writing .claude/ is appropriate
• Read versions from target (.claude/.prime-version) and prime (VERSION)

If the path fails those checks, abort and explain why.

2. Parallel Analysis

Change Detection:

• Detect relevant changes in prime's .claude/ based on the target's recorded version state
• If the target has no recorded version, or already matches the current prime version, sync only uncommitted prime changes
• If the target is on an older prime version, diff from that version tag to HEAD and include uncommitted changes; warn if the tag is missing
• Categorize changes into commands, agents, hooks, settings, skills, and starter-skills

Stack Detection (only if skills or starter-skills changed): check target for stack indicators relevant to each changed skill/starter.

File Comparison: compare each changed file with target. Detect: NEW, UPDATE, IDENTICAL, CONFLICT.

3. Build Sync Plan

Aggregate results and present:

CHANGED (will sync): ...
IDENTICAL (skip): ...
CONFLICTS (will ask): ...
IRRELEVANT (skip, wrong stack): ...

GATE: User approves sync plan.

4. Handle Conflicts

For each conflict, show the relevant diff and ask the user how to proceed:

• Overwrite — Replace the target copy with the prime version
• Skip — Leave the target copy unchanged
• Merge — Surface the full diff and let the user choose which parts to keep before writing anything

5. Execute Sync

1. Create .claude/ in target if needed
2. Copy approved files (skills as entire folders)
3. Sync approved starter-skills to .claude/starter-skills/ in target
4. Update .prime-version with prime's VERSION

6. Report

Sync complete! (prime vX.X.X)
Updated: ...
Skipped: ...
Version: X.X.X → written to .prime-version

Push mode only: update state file (lastSynced timestamp + version). Pull mode only: clean up /tmp/claude-prime-sync-* clone directory.

Gotchas

• prime-sync stays in prime — do not copy this skill into target projects.
• Push and pull keep different state — state file is push-only; pull mode treats the target as self-contained.
• Version history can be incomplete — if the expected tag is missing, warn and continue with that uncertainty explicit.

Constraints

• NEVER modify the target project's source code
• NEVER sync without user approval at the plan gate
• In push mode, preserve one state entry per target path and update it only after success
• In pull mode, always clean up the temporary clone, even on failure

Target Path

$ARGUMENTS

ultrathink.

How cook works

Cook is an incremental loop: break work into tasks, implement one, verify it works, move to the next. The key discipline is that nothing is "done" until there's evidence it works — but how you verify adapts to the situation.

Before you start

If the request is clear, start. If it's ambiguous or multi-faceted, ask clarifying questions. If the work is large or multi-path, plan first (/give-plan). Otherwise, just start.

The loop

1. Break into tasks only when it helps

For a small single-concern request, just implement, verify, and continue.

For multi-step work or collaboration, use .claude/scripts/tasks.py to track concrete outcomes. Task files persist in .tasks/, so a fresh context can pick up where the last one left off.

Every task requires three fields: title, desc, expected. Read the authoring rubric before writing tasks — bad tasks are worse than no tasks:

• .claude/scripts/tasks.py --help for the short-form rubric and examples
• .claude/scripts/tasks-authoring.md for the full guide

.claude/scripts/tasks.py --task-file <slug> add "<title>" "<desc>" "<expected>"
.claude/scripts/tasks.py --task-file <slug> list
.claude/scripts/tasks.py --task-file <slug> verify <id> "<evidence>"
.claude/scripts/tasks.py --task-file <slug> done <id>

2. Implement → Verify → Review → Next

Pick the next unblocked task, make the change, then hand off to a tester and (for risky work) a reviewer — isolated teammates that judge the change independently. See .claude/skills/test/teammate.md and .claude/skills/review-code/teammate.md for how to spawn them.

/cook owns implementation. The tester owns verification. Give the tester:

• the user-visible claim or acceptance criteria
• the files or behavior you changed
• the most likely regression surface
• any constraints that matter

You can still add durable tests, fixtures, or stable selectors when they belong to the product change itself. Do not stuff temporary verification tactics into /cook just to get through one run.

Before invoking verification, confirm the edits actually landed on disk. If the change you expect is missing from the diff, fix that first; a passing check against unchanged code is worthless evidence.

Do not mark a task done on confidence alone. The tester proves the behavior. The reviewer checks that the implementation is correct, scoped, and aligned with the repo. For risky or non-trivial work, spawn a reviewer before marking the task complete.

Update task status as you go so the execution trail stays trustworthy.

3. Review the whole change set

After the task list is complete, review the combined diff before declaring success. Cross-task issues often appear only in the final aggregate: mismatched assumptions, naming drift, incomplete ripple updates, or verification that was too narrow. Spawn a reviewer for this final pass.

4. Report

When done, summarize:

• what changed
• how each claim was verified
• decisions that materially shaped the implementation
• any follow-up the user should know about

Request

$ARGUMENTS

ultrathink

Process

Check conversation context and skip completed steps.

1. Identify the doc job

Figure out the document type, audience, purpose, whether to update an existing doc or create new, and what source material it draws from. If any of these would materially change the output and are unclear, ask.

If the request is still evaluating options, stop and discuss — drafting docs before a decision is made locks in the wrong answer.

If the doc type is a recognized structured format (runbook, ADR, postmortem, onboarding guide, API/architecture doc), read references/doc-types.md now — it has the required sections for each type.

2. Ground in evidence

Before writing factual claims, read relevant sources — existing docs, code, config, tickets, PRs, prior discussion. Don't present guesses as fact. Label uncertain details explicitly, or collect them in an "Open questions" section rather than hedging every sentence.

3. Choose destination

Prefer updating the canonical existing doc when one exists.

For new documents, MUST default to docs/ at the repo root (create it if missing). Only deviate when:

• A more specific existing doc home clearly fits (ADR directory, changelog, README section, established project docs tree) — use it
• The repo already follows a convention of keeping docs next to the code they explain — match that
• The doc is event-like (postmortem, incident note) — use a timestamped filename

When you need a fresh timestamp, use date +%Y%m%d%H%M%S.

4. Outline first when substantial

For large or structurally ambiguous docs, propose a title and section outline before drafting. For small or routine docs, write directly.

5. Write the artifact

Write the file at the path from Step 3 — don't paste in chat without creating the file. Adapt structure to the document type (ADRs, runbooks, postmortems, API docs, etc.) and include only sections that earn their keep.

A strong document is accurate, concise, audience-aware, scannable, explicit about why something matters, and clear about what is current behavior vs. decision vs. open question. Write for the intended reader, not for completeness theater. Prefer concrete repo-specific details over generic filler. When sources conflict, name the conflict instead of quietly picking one.

6. Report and stop

Report the path, whether you updated or created, what was captured, and any assumptions or gaps. Do not drift into implementation unless explicitly asked.

Topic

$ARGUMENTS

Think harder.

Process

Check conversation context and skip completed steps.

1. Understand the symptom

• Read the bug report, errors, logs, and surrounding code carefully
• Clarify reproduction steps, expected behavior, and environment when they are unclear
• Separate confirmed facts from working assumptions. List them explicitly:
  • Fact (confirmed): the server returns 200
  • Assumption (unconfirmed): the client receives the full HTML body Misidentifying an assumption as a fact is the most common source of wasted investigation.

2. Build hypotheses

• Form 2-4 plausible root-cause hypotheses that are mechanistically distinct — different failure layers (e.g., server render vs. client hydration vs. network layer), not variations of the same idea

• Rank them by likelihood

• For each hypothesis, state both sides:

  • Confirm if: [what observation would prove this is the cause]
  • Eliminate if: [what observation would rule this out]

  A hypothesis you can't falsify in both directions is too vague to test.

3. Choose the lightest evidence method

Start with the cheapest source of truth that can kill hypotheses:

• existing logs, traces, stack traces, metrics, and error output
• static code inspection around the suspected path
• config, environment, deploy, cache, queue, and permissions state that could explain the symptom
• targeted reproduction in the relevant environment

Only add new instrumentation when existing evidence is insufficient.

• If you need runtime probes, read diagnose/references/runtime-debugging.md
• Use #region agent log / #endregion markers for any instrumentation you add
• Tag each log point with the relevant hypothesisId
• Log only the minimum fields needed to discriminate between hypotheses; never log secrets, tokens, passwords, cookies, or full sensitive payloads
• If runtime probes require starting the local debug server, ask the user before launching it
• For browser/UI bugs, combine with the agent-browser skill when reproduction or inspection needs it

4. Gather evidence and iterate

• Use existing logs, traces, failing tests, or artifacts before asking for a fresh reproduction
• When reproduction is needed, ask the user to trigger the bug — tie each request to the hypothesis it tests
• Correlate each finding with the hypothesis it supports or eliminates; narrow based on evidence, not confidence
• If ambiguity remains, refine hypotheses and add narrower probes — but stop and report when another round is unlikely to produce new discriminating evidence

5. Report the diagnosis

Output structured diagnosis:

## Diagnosis: [Issue Title]

### Symptoms
- [What was observed]

### Evidence
- [Finding] — `file:line` or runtime source — hypothesis X
- ...

### Root Cause
[Confirmed or most likely cause, with evidence]

### Hypotheses Tested
| # | Hypothesis | Confirm if | Eliminate if | Result |
|---|-----------|-----------|-------------|--------|
| A | ... | [what observation would prove this] | [what observation would rule this out] | Confirmed/Eliminated/Inconclusive |

### Recommended Next Steps
- [What to do next — usually hand off to `/fix` with this diagnosis]

### Active Instrumentation
- [List files with `#region agent log` blocks still in place, or `None`]

Constraints

• NO fixing — investigation and diagnosis only. "Recommended Next Steps" hands off to /fix with the diagnosis; it does not prescribe specific parameter values, code snippets, or step-by-step implementation instructions.
• Evidence over assumptions — if the code looks wrong but runtime evidence says otherwise, trust the runtime
• If you add #region agent log blocks, leave them in place for /fix to verify the repair and call them out in the final report

Bug

$ARGUMENTS

ultrathink

How to think in this mode

The job is to help the user see the decision clearly — what's at stake, what they're missing, where the real tradeoffs are. Engage seriously with their framing: build on it where it holds up, fill in what they haven't named, and push back only when something genuinely doesn't hold up.

Do not implement. Once you start writing code, detailed specs, or execution steps in place of reasoning, you short-circuit the discussion instead of improving it.

Process

Check conversation context and skip completed steps.

1. Clarify (if needed)

• State your understanding of the topic
• Ask focused clarifying questions only when the topic is genuinely ambiguous

2. Ground the discussion (if needed)

• Read relevant files and search the codebase for existing patterns before making claims about the system
• Skip this when the needed facts are already clear from context

3. Pick the right decision lens

Don't force every discussion into the same pros/cons template. Match the lens to the problem:

• Technical or architecture choice — start from constraints, failure modes, maintenance burden, and irreversible decisions
• Product or strategy choice — anchor on user value, business impact, adoption friction, and opportunity cost
• Process or workflow issue — map the current state and bottlenecks before proposing changes
• High-uncertainty or novel territory — surface assumptions, unknowns, and what would invalidate each option

4. Analyze

• Break the problem into its key components
• Surface constraints, dependencies, and hidden assumptions, especially the ones the user has not named explicitly

5. Debate

• Only present options that are genuinely defensible
• If there is truly one strong path, say so directly instead of manufacturing weak alternatives
• Explain the real pros, cons, and tradeoffs of each viable option
• When an assumption looks weak or a constraint is being missed, name it and explain why — but only when there's a real concern, not to seem balanced
• End with a recommendation: "I think X is the right call because..."

6. Synthesize

• Land on a direction with clear rationale
• Call out unresolved items and whether they matter now or can wait
• Give concrete next steps for the user to take after the discussion
• If the discussion has clearly converged on a concrete decision or recommendation, and capturing it would likely save future rediscovery, optionally end with a brief offer to capture it in a durable doc via create-doc
• Keep that capture offer short and optional. Do not make it if the discussion is still exploratory, the decision is unsettled, or the user is clearly done and does not need another prompt

Tone calibration

Read the room. A peer asking for a blunt sanity check usually wants direct feedback. Someone deeply invested in an idea still needs honesty, but with more care in delivery. Adjust the tone without softening your actual reasoning.

Gotchas

• Reflexive pushback: Treating every input as something to challenge is just as bad as agreeing with everything — it's noise that makes the discussion worse and wears the user out. Pushback should only show up when you have a real concern (weak reasoning, ignored constraint, blind spot). If the user's framing holds up, say so and build forward; the value you add then is range, depth, and what they haven't considered — not always resistance
• Being a yes-man: The opposite failure — mirroring the user's framing back without adding anything. The fix isn't more pushback; it's bringing new information, context, or considerations they didn't have
• Opinions without evidence: If you're making claims about code, architecture, or current behavior, ground them in files or facts first
• Strawman options: Presenting one real option plus two weak ones is advocacy dressed up as debate. Every option should be one you could genuinely argue for. Bad: "Option A (the real answer), Option B (A but worse), Option C (obviously impractical)." Good: two genuinely different approaches with real tradeoffs, or just one clear recommendation if that's the honest answer
• Analysis paralysis: Endless pros/cons without a recommendation is a failure mode. Good-enough decisions beat perfect decisions that never happen
• Ignoring constraints: Time, budget, and team capability usually matter more than theoretical elegance
• Premature capture nudges: Only offer to write things up when there is a real conclusion worth preserving. Do not turn every discussion into a documentation prompt

Topic

$ARGUMENTS

Why fetch instead of recall

Trained knowledge rots. Library APIs rename fields, deprecate hooks, restructure auth flows, and change defaults between minor versions. Answering from memory is how you get confidently wrong code. Replace memory with retrieval — cheaply, from sources designed for AI consumption.

The source hierarchy (and why)

Prefer sources in this order. The ranking is about signal per token, not just availability.

1. llms.txt on the official docs site — hand-curated by the project, AI-optimized, token-dense, always current. This is the ideal source when it exists. Try {official-docs-url}/llms.txt first for any library with a docs site; many projects ship one even if they don't advertise it. If llms.txt is just an index of links, follow the most relevant ones. llms-full.txt exists on some sites and contains the full corpus — only reach for it when the user explicitly wants comprehensive docs, since it's large.

2. Context7 — a mirror that ingests GitHub repos and exposes them at https://context7.com/{org}/{repo}/llms.txt, with optional ?topic={keyword} filtering. Use this when the project has no official llms.txt, or when you want to scope to one feature. The {org}/{repo} path mirrors GitHub exactly — derive it from the user's package.json, imports, lockfile, or the project's GitHub URL rather than guessing. For docs sites without a clear repo, Context7 also hosts https://context7.com/websites/{normalized-path}/llms.txt.

3. GitMCP — any GitHub repo is accessible by swapping github.com → gitmcp.io in the URL. Useful when Context7 doesn't have the repo indexed, or when you need source-of-truth README/examples straight from the repo.

4. WebSearch — last resort. Slower, noisier, and you'll spend tokens filtering results. Only fall here when the three structured sources all miss. When you do search, query for "{library} llms.txt" first — it often surfaces an official or community-maintained one.

On any 404, timeout, or empty response: move to the next tier immediately. Never retry a failed source.

Topic scoping

When the user's query targets a specific feature (e.g., "shadcn date picker", "Next.js middleware", "Stripe webhooks"), append ?topic={keyword} to the Context7 URL to narrow the fetch. Pick a short root keyword that captures the feature — judgment call, no rigid rules. The goal is fewer tokens, higher relevance. If the topic URL returns nothing useful, drop the topic and try the general URL.

Reading the docs you find

Once you have URLs, the question is how to read them without polluting the main context.

• A handful of small pages, or content the orchestrator clearly needs verbatim: read directly with WebFetch. Fast, simple, no overhead.
• Many pages, or large pages where you only need specific answers: fan out to parallel subagents, each reading a subset and returning a condensed summary. This protects the main context window from doc bloat and parallelizes I/O. Use judgment on fan-out count — a couple for moderate sets, more for large ones. The tradeoff is latency/tokens vs. main-context pollution; lean toward subagents whenever the raw docs would be noisy relative to what the orchestrator actually needs.

When delegating to subagents, tell them exactly what question to answer and what to return (e.g., "return the exact signature and required fields for stripe.webhooks.constructEvent, plus any version notes") — not "summarize these docs". Specific asks give specific answers.

Version awareness

Before fetching, check what version the project actually uses — package.json, requirements.txt, go.mod, lockfiles. Fetching the latest docs when the project is pinned two majors behind is a common way to hand back wrong answers. If a version-specific doc path exists (e.g., /v2/llms.txt, /docs/4.x/), prefer it.

Gotchas

• Don't fabricate. If every source misses, say so clearly and ask the user for a URL or a different approach. A made-up API signature is worse than "I couldn't find it."
• Don't over-fetch. The orchestrator asked a question; pull what answers it, not the entire manual. Every token you add competes for attention downstream.
• Don't trust your own cache. If you recall that a library's docs live at a certain URL, verify — sites reorganize. A fresh fetch beats a confident memory.
• Report what you used. When you hand results back, note which source succeeded (llms.txt / Context7 / GitMCP / WebSearch) and the URLs fetched. This lets the orchestrator judge freshness and lets the user follow up.

Constraints

• Use WebFetch to read URLs. Do not invoke MCP servers for this.
• Prefer llms.txt over llms-full.txt unless comprehensive docs are explicitly requested.
• Never retry a failed source — move down the tier list.

Think harder. Remove the cause with the change that genuinely restores the intended behavior. Making the symptom disappear without explaining the evidence is not a fix.

Process

Check conversation context and skip completed steps.

1. Read the bug, then choose the lane

Read the symptom, expected behavior, errors, logs, failing tests, and any prior diagnosis. Separate confirmed facts from guesses. Then route:

If you're about to add a speculative guard or workaround because the cause is still fuzzy, you're in the wrong lane. If evidence is insufficient, switch to /diagnose instead of guessing.

GATE: If a plan was requested or produced, wait for user approval before implementation.

1.5 Reboot after repeated misses

After 3 substantive fix attempts that haven't resolved the bug, stop thrashing. Write a handoff note covering: bug context, confirmed evidence, files checked, each failed approach and why it failed, open questions, and most likely next diagnostic branch. Start a fresh Claude session with the handoff note (or give it to the user to paste). Repeated failures signal contaminated context or narrowed reasoning — a clean window gets fresh judgment. Let stop and enjoy the world, you just did the best thing bro!

2. Repair the cause

• Apply the smallest change that removes the root cause
• Correct the bad state transition, condition, query, or data flow rather than masking the symptom at the crash site
• Call-stack upstream rule: when a function crashes on bad data (undefined, null, wrong type), trace back to where that data was produced or passed. Fix the producer or caller, not the victim. Example: applyDiscount(cart, coupon) crashes because coupon is undefined → fix the lookup or call site that passed bad data, not applyDiscount
• Follow existing code patterns and keep scope tight
• Keep temporary instrumentation that helps prove the repair until verification is complete, then remove it

3. Verify with matching evidence

A repair is only done when the evidence matches the report. Prove three things: (1) the original failure is gone, (2) the repaired path was actually exercised, and (3) nearby behavior did not regress.

Hand off to a tester — an isolated teammate that verifies the repair independently. See .claude/skills/test/teammate.md for how to spawn one.

Add or update a durable test in /fix when covering the bug clearly belongs in the codebase. Otherwise the tester owns verification.

4. Clean up

Remove temporary debugging artifacts once verification passes: throwaway scripts, temp logs, or ad hoc instrumentation. Keep durable tests and intentional logging.

GATE: Do not call the bug fixed until the evidence directly addresses the reported failure.

Issue

$ARGUMENTS

This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.

The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.

Design Thinking

Before coding, understand the context and commit to a BOLD aesthetic direction:

• Purpose: What problem does this interface solve? Who uses it?
• Tone: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
• Constraints: Technical requirements (framework, performance, accessibility).
• Differentiation: What makes this UNFORGETTABLE? What's the one thing someone will remember?

CRITICAL: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.

Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:

• Production-grade and functional
• Visually striking and memorable
• Cohesive with a clear aesthetic point-of-view
• Meticulously refined in every detail

Frontend Aesthetics Guidelines

Focus on:

• Typography: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
• Color & Theme: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
• Motion: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
• Spatial Composition: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
• Backgrounds & Visual Details: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.

NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.

Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.

IMPORTANT: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.

Design Intelligence

Use the bundled design search tooling when you need concrete guidance that should shape implementation rather than generic inspiration.

Reach for .claude/skills/frontend-design/scripts/search.py when you need any of the following:

• a style direction that fits a product category or audience
• a color system, typography pairing, or chart recommendation
• UX or accessibility guidance for a specific interface problem
• stack-specific frontend advice for React, Next.js, Vue, Tailwind, and other supported stacks
• a full design-system recommendation grounded in the bundled dataset

Skip the search when the user already gave a precise visual direction and the implementation path is obvious.

Search Workflow

1. Start with the smallest query that captures the product or interface type.
2. Use auto-detection first; add --domain only when you know what kind of answer you need.
3. Add --stack when framework-specific implementation details matter.
4. Synthesize the retrieved guidance into one cohesive direction instead of pasting disconnected search results into the final answer.

Quick Start

# Auto-detect the best domain from a concise query
python3 .claude/skills/frontend-design/scripts/search.py "glassmorphism dark mode"

# Ask for a specific kind of guidance
python3 .claude/skills/frontend-design/scripts/search.py "healthcare saas" --domain colors

# Add framework context when implementation details matter
python3 .claude/skills/frontend-design/scripts/search.py "responsive layout" --stack html-tailwind

High-Value Defaults

Treat these as strong defaults, not blind rules:

• Prefer SVG icon systems over emoji so the UI feels product-grade and stylistically consistent.
• Keep clickable elements obviously interactive, including pointer cues where the platform expects them.
• Protect readability first; contrast and hierarchy matter more than visual gimmicks.
• In light mode, translucent surfaces need enough opacity to stay legible.
• Floating elements look more intentional when they breathe instead of touching viewport edges.
• Prefer hover treatments that preserve layout stability unless movement is a deliberate part of the concept.

References

• references/design-system-generation.md — use when the user wants a full design-system or style-guide recommendation for a project type (e.g. "SaaS dashboard", "e-commerce luxury", "fintech app") assembled from multiple search domains
• references/quality-checklist.md — use as the final self-critique pass before delivering UI work

Gotchas

• Defaulting to safe choices: Inter font + blue primary + white background is AI slop. Be distinctive.
• Using search as decoration: Retrieved guidance should change the design system or implementation decisions, not just add buzzwords.
• Inconsistent design system: Don't mix unrelated tokens or visual languages. Commit to one system throughout.
• Ignoring contrast ratios: WCAG AA minimum. Beautiful but unreadable is a failure.
• Purple gradients: The #1 AI cliché. Avoid unless specifically requested.
• Interaction polish gaps: Missing hover/focus states or weak affordances make even strong visuals feel unfinished.

Data Source

Remote: ui-ux-pro-max-skill

Available domains include styles, colors, typography, charts, products, landing, ux, icons, ui-reasoning, and web-interface. Supported stacks include html-tailwind, react, nextjs, astro, vue, nuxtjs, nuxt-ui, svelte, swiftui, react-native, flutter, shadcn, and jetpack-compose.

Search uses a cached BM25 ranking script over the remote dataset, so prefer concise, concrete queries over long prompt-like paragraphs.

Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.

ultrathink

Core contract

Figure out the right approach, write a plan the user can inspect, and stop. Planning is not approval to implement — wait for explicit go-ahead before writing any code.

• Clarify only what would materially change the plan.
• Read the codebase before making claims. Distinguish confirmed facts, inferences, and unknowns — never hide uncertainty.
• Optimize for reviewability over momentum.

If already in native plan mode, this skill shapes how to plan; plan mode provides the workflow structure and must follow this skill guidelines.

Process

Check conversation context and skip completed steps.

1. Clarify the planning goal

What kind of plan? Scoped implementation, phased feature, migration/rollout, architecture decision, or spec artifact. Ask only the questions that matter.

2. Ground in evidence

Read relevant files and search the codebase before proposing changes. Be explicit about what's confirmed from code vs. inferred vs. unknown.

3. Choose the right altitude

• Small change → concise plan with touchpoints and validation
• Multi-file feature → phased plan with dependencies
• Architecture choice → options, tradeoffs, recommendation
• Migration / rollout → sequencing, rollback, validation checkpoints

Don't force every request into the same template.

4. Write the plan (right-size the artifact)

Match artifact to plan size — don't force plans/*.md on small scoped changes.

• Inline prose — small single-file tweaks, quick scoped edits, brief decisions. Present the plan in the response and stop.
• plans/YYYYMMDDHHMMSS-{plan-name}.md — multi-file features, migrations, architecture decisions, anything that benefits from review or history.
• plans/YYYYMMDDHHMMSS-{plan-name}/plan.md + phase files — large multi-phase work where each phase warrants independent reading/editing.

Use date +%Y%m%d%H%M%S for timestamps.

A strong plan covers: problem summary, recommended approach, phases/workstreams, affected files/modules/systems, dependencies and sequencing, validation strategy, risks and mitigations, assumptions and open questions, non-goals when useful.

5. Present and stop

Summarize the recommendation, call out risks/assumptions/unknowns, clarify what needs user confirmation, then wait. Do not drift into coding.

Boundaries

• Prose, not code — describe what changes in prose (name the file, the concept); never include executable syntax (function bodies, JSX, SQL, migration scripts, shell commands). "Illustrative" snippets are still implementation code.
• Right-sized artifacts — don't force heavyweight structure onto small work; don't leave plans so abstract they name no touchpoints or validation path.
• Every plan needs a validation path — how will you know the implementation succeeded?
• Name concrete files, interfaces, and systems where possible. Surface tradeoffs instead of hiding them.

Request

$ARGUMENTS

Media Processor

Specialized tools for extracting precise visual details (exact colors, spacing, hierarchy), processing audio/video, and generating images.

Tools

All scripts live in scripts/ relative to this skill's directory. They auto-select the best model per task and handle retries, large file uploads, and error reporting.

Requires GEMINI_API_KEY in environment or .env in this skill's directory. Run any script with --help for setup details and available parameters.

Quick start — image analysis:

python <skill-dir>/scripts/gemini_batch_process.py \
  --files <image-path> \
  --task analyze \
  --prompt "<tailored prompt>" \
  --output <output-path>.md

Prompt Quality Matters

The prompt sent to the processing model is the single biggest factor in output quality. Tailor prompts to what the task actually needs — generic prompts produce generic results.

What makes a good analysis prompt:

• Ask for the specific details the task requires (hex colors, spacing in px, component hierarchy) rather than "describe this image"
• Structure the ask as a numbered list — the model mirrors the structure back, making output easy to parse
• Name the desired output format ("as a markdown table", "as JSON", "as a component tree")
• Include implementation context when relevant ("for React with Tailwind") so the model emphasizes useful details

Example prompt patterns:

UI implementation: "Extract component hierarchy, layout type, exact hex colors, typography (sizes/weights), spacing in px, interactive states, icons and decorative elements"

Chart data: "Extract chart type, axes with units, every data point with exact values, legend entries with colors. Output as a markdown table"

Design review: "Compare this screenshot against the design. Flag differences in spacing, colors, alignment, missing elements, and visual inconsistencies. Note exact values for each discrepancy"

Pasted Images

When a user pastes images in chat, they are auto-saved to:

$CLAUDE_DIR/image-cache/<current_session_id>/<image_number>.png

Use ls "$CLAUDE_DIR/image-cache/" to discover the session ID, then list its contents to find available images.

Model Overrides

Scripts auto-select models per task (see model-routing.md). Override with --model <model-id> when the default isn't enough — for example, --model gemini-3.1-pro-preview for complex visual analysis where the pro model catches more detail than flash.

References

Gotchas

• Rate limits — scripts retry up to 3 times with backoff. If still rate-limited after retries, stop and ask the user to check their API key quota or provide a new key.
• Model IDs change — Google frequently rotates preview model IDs. If you get a 404, the model was likely superseded — check the models page for current IDs.
• Safety filters — the API may refuse some content. Report clearly to the user rather than retrying.
• Large files auto-upload — files >20MB automatically use the File API (2GB max, 48h retention). No action needed.

Ultrathink.

Mission

Generate a Claude configuration that fits the specific project. Every skill, rule, and CLAUDE.md entry must exist because this project needs it — not because a template included it. Analyze the real codebase deeply, understand its conventions and patterns, and build a config that makes Claude work well here.

Modes

• Fresh prime — no claude config yet. Build from scratch.
• Re-prime — claude config already exists. Preserve intentional project work, refresh what is stale or generic, fill gaps.

Default to re-prime whenever meaningful existing config is found. Never overwrite it wholesale without user approval.

Flow

1. Analyze the repo deeply — stack, conventions, boundaries, docs, existing config. See analysis-checklist.md.
2. Propose findings using the Output Format below. Do not touch meaningful files before approval.
3. Create skills via /skill-creator — every skill must go through skill-creator to ensure quality and project fit. Starters in .claude/starter-skills/ are reference input to accelerate creation, not templates to copy.
4. Generate or refine CLAUDE.md — lean, high-signal, always-on context only. Point to docs/READMEs for detail.
5. Rules only if needed — apply the rule test. Zero rules is valid.
6. Offer CLAUDE.local.md — personal preferences (role, sandbox URLs, preferred test data, workflow quirks), gitignored.
7. Clean up — delete .claude/starter-skills/ after processing. Keep protected skills. Confirm all deletions.
8. Verify — references resolve, stack claims match evidence, config is project-specific not generic.
9. Offer skill optimization — after everything is set up, offer optimization paths sized to how many new skills were created. ≤3 skills: recommend full optimization for all. >3 skills: recommend full optimization for user-designated core skills only + description optimization for the rest (avoids long execution time and token burn). Always emphasize that full optimization takes meaningful time and tokens. Run sequentially — never in parallel; concurrent runs overload the user's machine.

Follow full step-by-step in setup-project.md.

Placement Decision Matrix

Every piece of knowledge must earn its place. Use this to decide where it belongs:

Principles

• Domain-scoped, project-fitted. Skills target a capability, not the project itself — with this project's patterns baked in. Generic templates and project-named catch-alls both degrade context quality.
• Repo evidence is the source of truth. Verify conventions from actual source files, configs, and docs. Do not assert what you haven't confirmed.
• Lean context, high signal. Follow the context engineering philosophy — load only what's needed, when it's needed. CLAUDE.md carries always-on essentials. Skills load on demand. Rules auto-attach by path.
• Rules are optional and path-scoped. Only create a rule when the rule test passes. Do not modify _apply-all.md — it is a universal boilerplate rule from prime, not project config.
• Reuse over duplication. If the project has strong docs, point to them. Do not re-author parallel agent docs unless existing material is too noisy or incomplete.

Output Format

Before making non-trivial changes, report findings in this shape:

Current State

What Claude config already exists; what the repo evidence says about stack, tooling, and conventions.

Proposed Changes

What to create, update, keep, or remove — including which skills to build and what each should cover.

Files to Touch

Concrete file list with short purpose notes.

Include these only when non-empty:

• Decisions Needing User Input — overwrites, deletions, or major structural changes
• Risks / Assumptions — inferred facts that still need verification

After approval, implement and finish with a short summary of what changed and any follow-ups.

References

Additional Context (Optional)

$ARGUMENTS

ultrathink

Process

Critique only — no fixes or implementation. Understand why the code exists before judging it.

1. Identify the review target

Prefer in order: explicit <target>, changes made in this conversation, working diff. If unclear, ask.

Then gather enough context (PR/issue text, plans, surrounding code) to avoid misreads. Don't turn every review into archaeology — if a missing detail would materially change judgment, ask briefly.

2. Match depth to risk

• Quick — small, local, low-risk; keep output brief
• Standard — normal feature or refactor
• Deep — risky, cross-cutting, security-sensitive, or surprising

3. Review flow first, then details

Understand how important parts work before commenting line by line. Focus on load-bearing logic, edge cases, scope drift, and intentional tradeoffs.

4. Report

For each finding: file path + line, why it matters, severity.

• Critical — correctness, safety, broken edge cases, scope violations. Requires evidence in the code — speculative failure modes belong in Questions.
• Suggestion — non-blocking improvements
• Question — missing context or unconfirmable concerns

If something looks odd but context supports it, acknowledge rather than flag.

5. Output format

## Code Review: [scope]

**Verdict: {Approve | Request Changes | Reject}**

### Inferred Intent
[Only when context supports it]

### Critical Issues (Must Fix)
- `path/to/file:line` — concise description. Why: [reason]

### Suggestions (Nice to Have)
- `path/to/file:line` — concise description

### Questions
- [Clarifications on intent or tradeoffs]

### Summary
[1-2 sentences]

Include only sections with content. Always include Verdict and Summary.

Boundaries

• Read surrounding code when the diff alone is misleading.
• Deliberate decisions (inline comments, user-stated tradeoffs) are not defects — raise as Question only with concrete evidence.
• Don't judge by personal preference when project fit explains the choice.
• Name the right approach ("needs parameterized queries") but don't write corrected code.

Target

$ARGUMENTS

ultrathink.

Wire Mode: Apply Self-Improvement Proposals

When scope is (none), or when pending proposals exist and user says "ok":

Fetching proposals:

python3 .claude/hooks/self-improve/self_improve_db.py resolve list

Step 0: Consolidate before showing

User attention is finite — showing 12 proposals when 4 are duplicates, 3 already exist in rules, and 2 are noise wastes their focus on what matters. Before presenting anything, read the existing config (.claude/rules/, CLAUDE.md, CLAUDE.local.md, active skills) to understand what's already there. Then filter: proposals already covered by existing rules, duplicates of each other, and low-value noise that wouldn't improve agent behavior. Merge proposals addressing the same pattern into one entry with the clearest rationale.

Tell the user what you filtered: "Showing X of Y proposals (Z filtered)."

After user finishes reviewing visible proposals, batch-reject the filtered ones:

python3 .claude/hooks/self-improve/self_improve_db.py resolve <id1>,<id2>,... rejected

For each shown proposal, ask the user to approve or reject.

Step 1: Classify — where does it belong?

~80% of proposals become rules — the pipeline detects behavioral corrections, and corrections are rules by definition.

Step 2: Read existing content, check for overlap

Read all files in the target location. Scan for semantic overlap — does an existing rule/section already cover this?

Step 3: Place — merge or add

• If overlap exists: merge into existing entry — expand/refine/strengthen, don't create near-duplicates
• If distinct: add under the most relevant section header

Writing quality — proposals describe specific incidents, but rules must work for the general case:

1. Generalize from the incident. The proposal says "Claude changed the pass dot when user meant N/A dot." The rule should address the class: "When multiple UI elements match an ambiguous reference, confirm which one before changing any." Don't encode the specific incident — encode the pattern.
2. Ground in reasoning, not commands. "ALWAYS confirm ambiguous references" is brittle — the agent doesn't know when it applies. "Because acting on the wrong target wastes a correction cycle, confirm which element when multiple candidates match" gives the agent judgment for edge cases.
3. Trim while merging. When adding to an existing rule file, read what's already there. If existing entries are redundant with the new content or with each other, consolidate. The goal after merging is a tighter file, not a longer one.
4. Watch for accumulation. If 3+ proposals have landed in the same file or section, that's a restructuring signal — the section may need splitting, or the underlying skill needs fixing instead of piling on more rules.
5. Think from the agent's perspective. Before finalizing, ask: "If I were an agent reading this rule for the first time with no context about the incident, would I understand when and why to apply it?" If the answer requires knowledge of the original proposal, rewrite.
6. Re-read with fresh eyes. After merging, re-read the entire section (not just your addition). Does the new content flow with the existing entries, or does it feel bolted on? Revise for coherence.

Step 4: Verify — smoke test

Use the proposal's rationale to construct a minimal replay prompt that would trigger the same mistake. Spawn a subagent with the new rule, give it the prompt, check if it avoids the failure. If it fails, revise once. If still fails, flag to user. Keep this fast — one prompt, one check.

Step 5: Resolve

python3 .claude/hooks/self-improve/self_improve_db.py resolve <id>[,<id>,...] approved  # or rejected

Step 6: Confirm

Tell the user: what was placed, where (file + section), why that location, and whether verification passed.

Manual reorganization

When invoked for rule reorganization (not proposals): read all .claude/rules/, identify duplicates/misplaced rules, propose consolidation plan, apply on approval.

Audit Mode: Proactive Config Analysis

When scope is full, skills, rules, claude-md, or quick. Also when (none) and no pending proposals found.

Phase 1: Understand the Project

1. Read package.json, pyproject.toml, go.mod, or equivalent — know the stack
2. Scan top-level directory structure — know the architecture
3. Read CLAUDE.md — know what config claims about the project
4. Read .claude/settings.json — know what hooks are configured
5. If .claude/hooks/self-improve/ exists, check for pending proposals: python3 .claude/hooks/self-improve/self_improve_db.py resolve list

Phase 2: Analyze

Read references/quality-dimensions.md for mechanical check scripts, staleness signals, and conflict resolution rules. Then run per-component analysis — see references/audit-guide.md for the full checklist covering skills, rules, CLAUDE.md, CLAUDE.local.md, and hooks.

Phase 3: Fix

Severity: CRITICAL (wrong code/skill, broken refs) → fix. MODERATE (suboptimal output) → fix if easy. LOW (style) → report only.

Fix: broken refs, inaccurate facts, trigger overlaps, weak/stale rules, redundant cross-layer content, broken hooks, orphaned project refs. Don't fix: workflow skill descriptions (report for skill-creator), substantial completeness gaps (report as recommendation), things that work.

Phase 4: Verify

For each fix: re-read, re-run the specific check, confirm it passes. Check no new broken refs introduced.

Phase 5: Report

Use the report template in references/audit-guide.md § Report Template. Health verdicts: HEALTHY (0 CRITICAL, ≤2 MODERATE) | NEEDS ATTENTION (unfixed MODERATE or 1 CRITICAL) | CRITICAL ISSUES (2+ CRITICAL).

Constraints

• Stay in your lane. Config quality + proposals only. Not for creating skills, priming projects, or fixing code bugs.
• Fix what's broken, not what's working. Respect knowledge layers: skills teach, rules guard, refs provide context.
• Don't bloat. If a fix requires 50+ new lines, report as recommendation.
• Don't weaken when merging. Combined version must be at least as strong as the original.

Skill Creator

Default operating mode: autonomous — create or update the skill, run evals, improve it, optimize the description, and return with a final report. Only pause for human review if the user explicitly requests it or you hit an ambiguity that can't be resolved from the evidence alone.

At a high level, the process of creating a skill goes like this:

• Decide what you want the skill to do and roughly how it should do it
• Write a draft of the skill
• Create a few test prompts and run claude-with-access-to-the-skill on them
• Evaluate the results both qualitatively and quantitatively
  • While the runs happen in the background, draft some quantitative evals if there aren't any (if there are some, you can either use as is or modify if you feel something needs to change about them)
  • Use the eval-viewer/generate_review.py script to show the results if the user wants to review
• Rewrite the skill based on eval results, benchmark data, and user feedback (if review was requested)
• Repeat until quality thresholds are met or the user is satisfied
• Optimize the description for triggering accuracy parallel

Figure out where the user is in this process and then jump in and help them progress through these stages. Route based on what they need. Of course, you should always be flexible and if the user is like "I don't need to run a bunch of evaluations, just vibe with me", you can do that instead.

Workspace convention: All eval artifacts go in tmp/<skill-name>-workspace/ under the project root (the directory containing .claude/). This directory is gitignored. Within the workspace, organize by iteration (iteration-1/, iteration-2/, etc.).

Nested invocation: When invoked as a subagent with an explicit outputs directory, use that outputs/ directory as the root for all inner workspaces — not tmp/<skill-name>-workspace/.

Track your progress with tasks/todos — without them, description optimization and the judge step are commonly skipped.

Communicating with the user

The skill creator is liable to be used by people across a wide range of familiarity with coding jargon. If you haven't heard (and how could you, it's only very recently that it started), there's a trend now where the power of Claude is inspiring plumbers to open up their terminals, parents and grandparents to google "how to install npm". On the other hand, the bulk of users are probably fairly computer-literate.

So please pay attention to context cues to understand how to phrase your communication! In the default case, just to give you some idea:

• "evaluation" and "benchmark" are borderline, but OK
• for "JSON" and "assertion" you want to see serious cues from the user that they know what those things are before using them without explaining them

It's OK to briefly explain terms if you're in doubt, and feel free to clarify terms with a short definition if you're unsure if the user will get it.

Creating a skill

Capture Intent

Start by understanding the user's intent. The current conversation might already contain a workflow the user wants to capture (e.g., they say "turn this into a skill"). If so, extract answers from the conversation history first — the tools used, the sequence of steps, corrections the user made, input/output formats observed. Skip if in autonomous mode: The user may need to fill the gaps, and should confirm before proceeding to the next step.

1. What should this skill enable Claude to do?
2. When should this skill trigger? (what user phrases/contexts)
3. What's the expected output format?
4. What evaluation strategy fits? Objectively verifiable outputs (file transforms, code generation) → expectations and baselines. Subjective outputs (writing style, art) → qualitative analysis.

Skip if in autonomous mode: If a gap is genuinely irresolvable from context and would materially change the skill's correctness, pause and ask. Otherwise infer, state it, and proceed.

Interview and Research

Proactively ask questions about edge cases, input/output formats, example files, success criteria, and dependencies. Wait to write test prompts until you've got this part ironed out. SKIP this interview in autonomous mode, let make decisions yourself

Research existing skills — MUST read references/available-skill-resources.md for curated skill repositories, then fetch the README or index of relevant repos to check whether skills for this domain already exist. Don't deep-dive into repos with nothing relevant — a quick scan of the index is enough to know if there's something worth borrowing.

Check available MCPs - if useful for research (searching docs, finding similar skills, looking up best practices), research in parallel via subagents if available, otherwise inline. Come prepared with context to reduce burden on the user.

Write the SKILL.md

Based on the user interview, fill in these components:

• name: Skill identifier
• description: When to trigger, what it does. This is the primary triggering mechanism - include both what the skill does AND specific contexts for when to use it. All "when to use" info goes here, not in the body. Note: currently Claude has a tendency to "undertrigger" skills -- to not use them when they'd be useful. To combat this, please make the skill descriptions a little bit "pushy". So for instance, instead of "How to build a simple fast dashboard to display internal Anthropic data.", you might write "How to build a simple fast dashboard to display internal Anthropic data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'" Length: hard limit is 1024 characters (the optimizer enforces this); aim for under ~650 characters in practice — past that, every extra clause competes for attention with the other skills' descriptions and tends to dilute rather than sharpen triggering.
• compatibility: Required tools, dependencies (optional, rarely needed)
• the rest of the skill :)

Skill Writing Guide

Anatomy of a Skill

skill-name/
├── SKILL.md (required)
│   ├── YAML frontmatter (name, description required)
│   └── Markdown instructions
└── Bundled Resources (optional)
    ├── scripts/    - Executable code for deterministic/repetitive tasks
    ├── references/ - Docs loaded into context as needed
    └── assets/     - Files used in output (templates, icons, fonts)

Progressive Disclosure

Skills use a three-level loading system:

1. Metadata (name + description) - Always in context (~100 words)
2. SKILL.md body - In context whenever skill triggers (<500 lines ideal)
3. Bundled resources - As needed (unlimited, scripts can execute without loading)

These word counts are approximate and you can feel free to go longer if needed.

Key patterns:

• Keep SKILL.md under 500 lines; if you're approaching this limit, add an additional layer of hierarchy along with clear pointers about where the model using the skill should go next to follow up.
• Reference files clearly from SKILL.md with guidance on when to read them
• For large reference files (>300 lines), include a table of contents
• Routing lives at the parent. "When to use" conditions go in the SKILL.md reference table — not inside the spoke file. By the time the agent reads a "## When to Use" section, it's already paid the load cost. Reference files cover HOW; parent covers WHEN.

Domain organization: When a skill supports multiple domains/frameworks, organize by variant:

cloud-deploy/
├── SKILL.md (workflow + selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

Claude reads only the relevant reference file.

Principle of Lack of Surprise

This goes without saying, but skills must not contain malware, exploit code, or any content that could compromise system security. A skill's contents should not surprise the user in their intent if described. Don't go along with requests to create misleading skills or skills designed to facilitate unauthorized access, data exfiltration, or other malicious activities. Things like a "roleplay as an XYZ" are OK though.

Writing Patterns

Prefer using the imperative form in instructions.

Defining output formats - You can do it like this:

## Report structure
ALWAYS use this exact template:
# [Title]
## Executive summary
## Key findings
## Recommendations

Examples pattern - It's useful to include examples. You can format them like this (but if "Input" and "Output" are in the examples you might want to deviate a little):

## Commit message format
**Example 1:**
Input: Added user authentication with JWT tokens
Output: feat(auth): implement JWT-based authentication

Writing Style

Try to explain to the model why things are important in lieu of heavy-handed musty MUSTs. Use theory of mind and try to make the skill general and not super-narrow to specific examples. Start by writing a draft and then look at it with fresh eyes and improve it.

Test Cases

After writing the skill draft, come up with 2-3 realistic test prompts — the kind of thing a real user would actually say. Share them with the user if they want to review: "Here are a few test cases I'd like to try. Do these look right, or do you want to add more?" In autonomous mode, proceed directly.

Save test cases to <workspace>/evals.json. Don't write expectations yet — just the prompts. You'll draft expectations in Step 2 while the runs are in progress.

{
  "skill_name": "example-skill",
  "evals": [
    {
      "id": 1,
      "prompt": "User's task prompt",
      "expected_output": "Description of expected result",
      "files": []
    }
  ]
}

See references/schemas.md for the full schema (including the expectations field).

Good test cases are realistic (messy, specific — what a real user would type), substantive (complex enough that the skill makes a difference), diverse (different use cases, not three variations of the same prompt), and discriminating (test skill-specific behaviors, not generic task completion — ask "would bare Claude pass this?" and if yes, make it harder).

Also prepare 20 trigger eval queries for description optimization and save to <workspace>/trigger-eval.json. See the Description Optimization section below for the format. Doing this now means description optimization can launch immediately.

Running and evaluating test cases

This section is one continuous sequence — don't stop partway through. Do NOT use /skill-test or any other testing skill.

Within the workspace, organize results by iteration (iteration-1/, iteration-2/, etc.) and within that, each test case gets a descriptive directory name (e.g., handle-multi-page-pdf/). Don't create all of this upfront — just create directories as you go.

Step 0: Launch description optimization in the background

Description optimization only depends on the frontmatter description and trigger eval queries — it's independent of the skill body. Run it in parallel with the eval loop:

cd <skill-creator-dir> && python -m scripts.run_loop \
  --eval-set <workspace>/trigger-eval.json \
  --skill-path <path-to-skill> \
  --model <model-id-powering-this-session> \
  --max-iterations 5 --report none --verbose \
  --output <workspace>/run-loop-results.json \
  > <workspace>/run-loop.log 2>&1 &
echo "run_loop PID: $!"

Save the PID — you'll need it later to check completion. Continue immediately to Step 1.

Step 1: Spawn eval runs

Every eval must use a real subagent that actually executes the task. Reading a skill and imagining it would work is not evaluation — it's guesswork. Spawn all test cases in parallel, each as a separate subagent:

Execute this task with the following skill loaded.

Read the skill at [skill SKILL.md path] first — it contains your instructions.

Task: [eval prompt]
Input files: [eval files if any, or "none"]
Save outputs to: [workspace path]/iteration-[N]/[eval-name]/with_skill/outputs/
Outputs to save: [what the user cares about — e.g., "the .docx file", "the final CSV"]

Also required: write `outputs/transcript.md` — one line per tool call, in order, as you go: `- <Tool> | <key args> | <ok|error>`. Graders use this to verify process assertions. No transcript = failed process assertions.

Do NOT revert or clean up the project after completing the task. The orchestrator handles cleanup after grading.

Project cleanup timing: Executors must not revert changes — doing so destroys evidence before graders can inspect it (new files, diffs, task artifacts). The orchestrator is responsible for restoring the project state after all graders have finished. This sequence matters: grade first, clean second.

Baseline runs (new skills only) — When creating a new skill, the first iteration MUST include baseline runs alongside with-skill runs. Run the same prompts without the skill loaded and save outputs to without_skill/outputs/. This measures whether the skill actually adds value over bare Claude. For subsequent iterations, baseline from iteration 1 still applies — no need to rerun.

Baseline runs for existing skills — When improving an existing skill, baseline runs are optional. Only run them when the user explicitly requests comparison. Existing skills have already proven their value.

Write an eval_metadata.json for each test case (expectations can be empty for now). Give each eval a descriptive name based on what it's testing — not just "eval-0". Use this name for the directory too. If this iteration uses new or modified eval prompts, create these files for each new eval directory — don't assume they carry over from previous iterations.

{
  "eval_id": 0,
  "eval_name": "descriptive-name-here",
  "prompt": "The user's task prompt",
  "expectations": []
}

Step 2: While runs are in progress, draft expectations

Don't just wait for the runs to finish — you can use this time productively. Draft quantitative expectations for each test case. Good expectations are objectively verifiable and have descriptive names — they should read clearly in the benchmark viewer so someone glancing at the results immediately understands what each one checks. Subjective skills (writing style, design quality) are better evaluated qualitatively — don't force expectations onto things that need human judgment.

Write expectations that test what the skill specifically teaches, not just structural presence. Before writing each one, ask: "Would bare Claude likely get this right without the skill?" If yes, the expectation isn't discriminating — make it harder. Target project-specific conventions, ordering/sequencing the skill introduces, and exact implementation details (column names, error codes, ID formats) rather than topic mentions.

Update the eval_metadata.json files and evals.json with the expectations once drafted.

Step 3: As runs complete, capture timing data

When each subagent task completes, you receive a notification containing total_tokens and duration_ms. Save this data immediately to timing.json in the run directory:

{
  "total_tokens": 84852,
  "duration_ms": 23332,
  "total_duration_seconds": 23.3
}

This is the only opportunity to capture this data — it comes through the task notification and isn't persisted elsewhere. Process each notification as it arrives rather than trying to batch them.

Step 4: Grade, aggregate, and analyze

Once all runs are done:

1. Grade each run — spawn grader subagents in parallel (one per eval case), or grade inline for simple expectations. Each reads agents/grader.md and evaluates expectations against the outputs. When spawning, pass these inputs explicitly:

   Read agents/grader.md at <skill-creator-path>/agents/grader.md — it contains your role.
   
   transcript_path: <run>/outputs/transcript.md
   outputs_dir: <run>/outputs/
   expectations: [...]
   

   Save results to grading.json in each run directory. The grading.json expectations array must use the fields text, passed, and evidence — the viewer depends on these exact field names. For expectations that can be checked programmatically, write and run a script rather than eyeballing it.

2. Aggregate into benchmark — run the aggregation script from the skill-creator directory:

   python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
   

   This produces benchmark.json and benchmark.md with pass_rate, time, and tokens for each configuration. If generating benchmark.json manually, see references/schemas.md for the exact schema.

3. Do an analyst pass — read the benchmark data and surface patterns the aggregate stats might hide. See agents/analyzer.md for what to look for — non-discriminating expectations, high-variance evals, time/token tradeoffs, and repeated failure modes that should become skill instructions or bundled scripts.

4. Spawn a judge agent to evaluate quality and decide whether to continue, stop, or revise evals. The judge runs on every iteration including iteration 1 — if the skill is already good enough, there's no reason to burn another iteration. Always spawn the judge with model: "opus" — judgment calls benefit from the most capable model:

   Read agents/judge.md at <skill-creator-path>/agents/judge.md — it contains your role and output format.
   
   Then evaluate:
   - Previous benchmark: `<workspace>/iteration-<N-1>/benchmark.md` (skip for iteration 1)
   - Current benchmark: `<workspace>/iteration-<N>/benchmark.md`
   - Remaining failures: [paste analyst notes]
   - Skill diff: [paste the diff of what changed, or "Initial version" for iteration 1]
   

   Save the full output to <workspace>/iteration-<N>/judge-output.json.

   Trust the judge's decision. If it says stop, stop. Don't override.

   Stop thresholds (all must be met):

   • Pass rate ≥ 80% from real agent runs
   • Quality score ≥ 8.0 per the judge's rubric
   • Eval confidence = "high" or "medium"

5. If the user wants review, launch the viewer:

   nohup python <skill-creator-path>/eval-viewer/generate_review.py \
     <workspace>/iteration-N \
     --skill-name "my-skill" \
     --benchmark <workspace>/iteration-N/benchmark.json \
     > /dev/null 2>&1 &
   VIEWER_PID=$!
   

   For iteration 2+, also pass --previous-workspace <workspace>/iteration-<N-1>.

   If staying autonomous, write down iteration takeaways: what failed, why, and whether the skill is beating the baseline.

Assertion Quality Gate (new skills, iteration 1 only)

After aggregating benchmark data for the first iteration of a new skill, check whether the assertions are actually discriminating:

1. Compare with-skill vs without-skill pass rates. If the delta is less than 15%, the assertions likely aren't testing skill-specific behavior — bare Claude can pass them too.
2. If both score 100%, the assertions are definitively non-discriminating. The eval set needs revision before continuing.

When the gate fails:

• Pause the improvement loop
• Review grader eval_feedback for flagged weak assertions
• Revise assertions to test project-specific knowledge, skill-specific workflows, or behaviors Claude wouldn't exhibit without the skill
• Restart iteration 1 with the revised assertions

Do NOT mix assertion revisions with skill improvements across iterations — changing what you measure while changing what you're testing makes it impossible to track whether the skill actually improved.

This gate does not apply to existing skill improvements (no baseline data to compare against).

Step 5: Read feedback (if review was requested)

When the user tells you they're done, read feedback.json. Empty feedback means the user thought it was fine. Focus your improvements on the test cases where the user had specific complaints. Kill the viewer when done (kill $VIEWER_PID 2>/dev/null).

Improving the skill

This is the heart of the loop. You've run the test cases, you have benchmark data, and now you need to make the skill better.

How to think about improvements

1. Generalize from the evidence. The big picture thing that's happening here is that we're trying to create skills that can be used a million times (maybe literally, maybe even more who knows) across many different prompts. Here you're iterating on only a few examples because it helps move faster. But if the skill works only for those examples, it's useless. Rather than put in fiddly overfitty changes, or oppressively constrictive MUSTs, if there's some stubborn issue, you might try branching out and using different metaphors, or recommending different patterns of working. It's relatively cheap to try and maybe you'll land on something great.

2. Keep the prompt lean. Remove things that aren't pulling their weight. Make sure to read the transcripts, not just the final outputs — if it looks like the skill is making the model waste a bunch of time doing things that are unproductive, you can try getting rid of the parts of the skill that are making it do that and seeing what happens.

3. Explain the why. Try hard to explain the why behind everything you're asking the model to do. Today's LLMs are smart. They have good theory of mind and when given a good harness can go beyond rote instructions and really make things happen. Even if the feedback is terse or frustrated, try to actually understand the task and why the user is writing what they wrote, and what they actually wrote, and then transmit this understanding into the instructions. If you find yourself writing ALWAYS or NEVER in all caps, or using super rigid structures, that's a yellow flag — if possible, reframe and explain the reasoning so that the model understands why the thing you're asking for is important. That's a more humane, powerful, and effective approach.

4. Look for repeated work across test cases. Read the transcripts from the test runs and notice if the subagents all independently wrote similar helper scripts or took the same multi-step approach to something. If all 3 test cases resulted in the subagent writing a create_docx.py or a build_chart.py, that's a strong signal the skill should bundle that script. Write it once, put it in scripts/, and tell the skill to use it. This saves every future invocation from reinventing the wheel.

This task is pretty important and your thinking time is not the blocker; take your time and really mull things over. I'd suggest writing a draft revision and then looking at it anew and making improvements. Really do your best to get into the head of the user and understand what they want and need.

The iteration loop

After improving the skill:

1. Apply your improvements
2. Write <workspace>/iteration-<N+1>/skill_changes.json documenting what changed:

   ["Added error handling section", "Removed redundant examples", "Bundled helper script"]
   

   Each entry should be a human-readable string. For iteration 1, write ["Initial version"].
3. Rerun all test cases into iteration-<N+1>/ (with-skill only — baseline from iteration 1 still applies)
4. Grade, aggregate, analyze, and judge (Steps 2-4 above — the judge runs every iteration)
5. If the user asked for review, launch the reviewer with --previous-workspace pointing at the previous iteration

Safety limit: pause at 3 iterations. The judge should stop this at 1-2 naturally. Reaching 3 without meeting thresholds means something structural is wrong — stop and diagnose whether the problem is the skill or the test cases. If the root cause is bad test cases, rewrite evals rather than continuing.

Keep going until:

• The judge says stop (autonomous mode)
• The user says they're happy (interactive mode)
• The feedback is all empty (everything looks good)
• You're not making meaningful progress

Advanced: Blind comparison

For situations where you want a more rigorous comparison between two versions of a skill (e.g., the user asks "is the new version actually better?"), there's a blind comparison system. Read agents/comparator.md and agents/analyzer.md for the details. The basic idea is: give two outputs to an independent agent without telling it which is which, and let it judge quality. Then analyze why the winner won.

This is optional, requires subagents, and most users won't need it. The human review loop is usually sufficient.

Description Optimization

The description field in SKILL.md frontmatter is the primary mechanism that determines whether Claude invokes a skill. If you launched description optimization in Step 0 during the eval loop, check on it now. Otherwise, run it after the skill body is finalized.

Step 1: Generate trigger eval queries

Create 20 eval queries — a mix of should-trigger and should-not-trigger. Save as JSON:

[
  {"query": "the user prompt", "should_trigger": true},
  {"query": "another prompt", "should_trigger": false}
]

The queries must be realistic and something a Claude Code or Claude.ai user would actually type. Not abstract requests, but requests that are concrete and specific and have a good amount of detail. For instance, file paths, personal context about the user's job or situation, column names and values, company names, URLs. A little bit of backstory. Some might be in lowercase or contain abbreviations or typos or casual speech. Use a mix of different lengths, and focus on edge cases rather than making them clear-cut (the user will get a chance to sign off on them).

Bad: "Format this data", "Extract text from PDF", "Create a chart"

Good: "ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think"

For the should-trigger queries (8-10), think about coverage. You want different phrasings of the same intent — some formal, some casual. Include cases where the user doesn't explicitly name the skill or file type but clearly needs it. Throw in some uncommon use cases and cases where this skill competes with another but should win.

For the should-not-trigger queries (8-10), the most valuable ones are the near-misses — queries that share keywords or concepts with the skill but actually need something different. Think adjacent domains, ambiguous phrasing where a naive keyword match would trigger but shouldn't, and cases where the query touches on something the skill does but in a context where another tool is more appropriate.

The key thing to avoid: don't make should-not-trigger queries obviously irrelevant. "Write a fibonacci function" as a negative test for a PDF skill is too easy — it doesn't test anything. The negative cases should be genuinely tricky.

Step 2: Review with user (or skip in autonomous mode)

Present the eval set to the user for review using the HTML template:

1. Read the template from assets/eval_review.html
2. Replace the placeholders:
   • __EVAL_DATA_PLACEHOLDER__ → the JSON array of eval items (no quotes around it — it's a JS variable assignment)
   • __SKILL_NAME_PLACEHOLDER__ → the skill's name
   • __SKILL_DESCRIPTION_PLACEHOLDER__ → the skill's current description
3. Write to a temp file (e.g., /tmp/eval_review_<skill-name>.html) and open it: open /tmp/eval_review_<skill-name>.html
4. The user can edit queries, toggle should-trigger, add/remove entries, then click "Export Eval Set"
5. The file downloads to ~/Downloads/eval_set.json — check the Downloads folder for the most recent version

In autonomous mode, skip this step and proceed directly to the optimization loop.

Step 3: Run the optimization loop

cd <skill-creator-dir> && python -m scripts.run_loop \
  --eval-set <path-to-trigger-eval.json> \
  --skill-path <path-to-skill> \
  --model <model-id-powering-this-session> \
  --max-iterations 5 --report none --verbose \
  --output <workspace>/run-loop-results.json \
  > <workspace>/run-loop.log 2>&1 &
echo "run_loop PID: $!"

Use the model ID from your system prompt (the one powering the current session) so the triggering test matches what the user actually experiences.

This handles the full optimization loop automatically. It splits the eval set into 60% train and 40% held-out test, evaluates the current description (running each query 3 times to get a reliable trigger rate), then calls Claude to propose improvements based on what failed. It re-evaluates each new description on both train and test, iterating up to 5 times.

How skill triggering works

Understanding the triggering mechanism helps design better eval queries. Skills appear in Claude's available_skills list with their name + description, and Claude decides whether to consult a skill based on that description. The important thing to know is that Claude only consults skills for tasks it can't easily handle on its own — simple, one-step queries like "read this PDF" may not trigger a skill even if the description matches perfectly, because Claude can handle them directly with basic tools. Complex, multi-step, or specialized queries reliably trigger skills when the description matches.

This means your eval queries should be substantive enough that Claude would actually benefit from consulting a skill. Simple queries like "read file X" are poor test cases — they won't trigger skills regardless of description quality.

Step 4: Apply the result

Take best_description from <workspace>/run-loop-results.json and update the skill's SKILL.md frontmatter. Show the user before/after and report the scores.

If best_description is unchanged from the original (the loop found no improvement), you have two options: (1) accept the original and stop, or (2) manually write a new candidate based on the failing test queries. If you choose (2), rerun the loop with --description-override "<candidate>" before applying — never apply an untested manual description directly to SKILL.md.

Final Report

Always generate and open a visual HTML report:

python <skill-creator-path>/eval-viewer/generate_report.py \
  <workspace> \
  --skill-name "<name>" \
  --run-loop-results <workspace>/run-loop-results.json \
  -o <workspace>/report.html

The --run-loop-results flag is optional — include it only if description optimization was run. After generating: open <workspace>/report.html

Include a brief text summary: what you changed and why, key outcomes, description optimization result, any remaining risks.

If the user asked whether a skill is ready to ship, give a direct recommendation: Ship, Ship with caveats, or Not ready — with specific reasons.

Packaging: For a distributable .skill file, run python -m scripts.package_skill <path/to/skill-folder>.

Reference files

The agents/ directory contains instructions for specialized subagents. Read them when you need to spawn the relevant subagent.

• agents/grader.md — How to evaluate expectations against outputs
• agents/judge.md — Independent agent that decides whether to continue or stop iterating
• agents/comparator.md — How to do blind A/B comparison between two outputs
• agents/analyzer.md — How to analyze why one version beat another

The references/ directory has additional documentation:

• references/schemas.md — JSON structures for evals.json, grading.json, benchmark.json, etc.
• references/available-skill-resources.md — Curated skill repositories for research

The core loop, one more time:

• Figure out what the skill is about
• Draft or edit the skill
• Run claude-with-access-to-the-skill on test prompts
• Evaluate the outputs (grade, benchmark, review if requested)
• Improve and repeat until thresholds met
• Optimize the description
• Generate final report

Track these steps with tasks/todos to make sure nothing gets skipped. Good luck!

Route fast

Skip steps whose answers are already known from the conversation.

Flow

1. Define the claim

Figure out what must be true before running anything.

Possible sources:

• explicit argument
• stated request or acceptance criteria
• recent conversation
• recent diff or git status as fallback

Good claim: expired tokens return 401. Bad claim: the app works.

If the claim is mushy, sharpen it before you touch the tools. Weak claims create noisy verification.

2. Scope only when needed

Skip if the claim is already scoped.

Use the change set to identify:

• deliverables — what must hold true
• coverage — what existing tests or manual checks could prove each deliverable
• blast radius — what nearby behavior could regress

For shared code, config, auth, schema, or similar cross-cutting changes, read references/regression-strategy.md before deciding how wide to test.

3. Find the project's real test entrypoints

Check in this order:

1. CLAUDE.md
2. package.json, Makefile, justfile, Taskfile
3. CI config
4. test framework config
5. existing test layout

Prefer project-defined commands over raw framework commands.

4. Choose the proof lane

Match the claim to the execution lane.

Once you've picked a lane, read the relevant reference before executing. Let the reference own the execution details.

Reference map

• references/backend-verification.md — API, DB, services, and background jobs
• references/frontend-verification.md — browser, component, and visual verification
• references/regression-strategy.md — how wide to test once the main claim is proven

The right method is the one that can disprove the claim fastest without pretending to offer more confidence than it really does.

If no relevant tests exist, use a manual path instead of calling the result inconclusive. Follow the selected lane's reference rather than rebuilding the checklist inline.

For command-line claims, run the command and inspect output directly.

Keep these guardrails in mind:

• once a lane is chosen, follow its reference instead of rebuilding the same checklist inline
• keep verification outcome-first: prove the user-visible or system-visible result, not just an intermediate action
• when regression is warranted, widen in rings: direct dependents → feature area → full suite

Only use INCONCLUSIVE when neither an automated path nor a manual path is feasible.

5. Pre-flight and execute

Before running verification, confirm required infra is already available. If a server, DB, queue worker, mock service, or migration is needed and not running, stop and tell the user the exact command to start it. Do not start it yourself.

When you run verification, capture evidence:

• exact command
• exit code
• relevant output
• non-zero test count when a suite was run
• warnings, skipped tests, and flaky behavior that matter to the claim

Start with the most direct proof. Expand into broader regression only when the blast radius justifies it.

6. Report

Use this structure:

## Verification Report

**Claim**: {what was tested}
**Verdict**: CONFIRMED | REFUTED | PARTIAL | INCONCLUSIVE

### Evidence
- {command}: exit {code} — proves or refutes {deliverable}

### Failures
- {test or command}: {error snippet} — {what it means}

### Gaps
- {deliverable or regression area still unverified}

### Suite Stats
Total: X | Passed: X | Failed: X | Skipped: X | Duration: Xs
Coverage: Lines X% | Branches X% (if available)

Use these verdicts consistently:

• CONFIRMED — every deliverable has passing evidence
• REFUTED — at least one deliverable failed with clear evidence
• PARTIAL — some deliverables are proven, others remain unverified
• INCONCLUSIVE — verification was blocked by missing infra, environment issues, or unavailable access

Common verification situations

Bug-fix verification

Prove the original failure no longer reproduces and check one regression ring around the changed area.

Feature verification

Prove the stated acceptance criteria and include type-check evidence when that meaningfully covers changed contracts.

Standalone verification

Take the claim from the argument or, if needed, infer it from recent changes.

Rules

• Run and report only. Do not fix failures.
• A passing suite is not proof if it never exercised the claim.
• Coverage gaps stay in the report even when existing tests pass.
• Flaky behavior and pre-existing failures are findings, not noise.
• If a lane points to a reference, read it before improvising tactics.
• Temporary, verification-only app changes are allowed when they make the proof materially better and the app is ours to edit. Keep them minimal, use them to verify the claim, then remove them before reporting.
• Do not leave verification hooks behind unless the user asked for a durable selector as part of the product change.
• Never start dev servers, databases, builds, or migrations yourself.

Verification Target

$ARGUMENTS

Backend FastAPI Python

Project-specific conventions for FastAPI with SQLModel, pydantic-settings, and async SQLAlchemy.

Architecture Decisions

1. Services are stateless functions — Not classes. First param is db: AsyncSession.
2. Generic response wrapper — Always use ApiResponse[T] for consistency.
3. Dependencies chain — get_current_user -> require_auth -> require_admin.
4. Module-scoped config — Each module can have its own {module}_config.py.
5. Error codes for frontend — AppException(status, message, error_code).

Gotchas

• SQLModel Relationship() fields are NOT included in API responses by default. You must explicitly add them to model_config or use a separate response schema with those fields.
• AsyncSession.refresh() does not load relationships. After commit, re-query with .options(selectinload(...)) if you need related objects.
• Pydantic V2 uses model_validator not validator. The @validator decorator is V1 and will break silently or raise deprecation warnings.
• Depends() in FastAPI creates a NEW instance per request — don't store state in dependency return values expecting it to persist.
• Background tasks (BackgroundTasks) run AFTER the response is sent. If they fail, the client already got a 200. Use proper task queues (Celery, ARQ) for anything that must not silently fail.
• Alembic --autogenerate misses: table renames (generates drop+create), index changes on existing columns, and Enum type modifications in PostgreSQL. Always review generated migrations.
• async def endpoints block the event loop if you call sync I/O inside them. Use run_in_executor for sync libraries or define the endpoint as def (FastAPI runs sync endpoints in a threadpool).
• HTTPException from FastAPI and HTTPException from Starlette are different classes. Importing the wrong one causes middleware to miss exception handlers.
• SQLAlchemy's lazy="selectin" on relationships causes N+1 queries in async sessions. Use explicit selectinload() in queries instead.
• Optional[str] = None in query params makes the field optional. str = None also works but loses type information — prefer the explicit Optional form.
• When using response_model, FastAPI filters OUT any fields not in the model. If your response is missing data, check that the response model includes all fields, not just the ORM model.

References

Docker

Project-specific containerization patterns for Dockerfile and Docker Compose.

Architecture Decisions

Image Building

1. Minimal base images — Use slim/alpine variants; pin to digest for reproducibility.
2. Multi-stage builds — Separate build dependencies from runtime.
3. Layer optimization — Combine RUN commands; place frequently changed files last.
4. COPY over ADD — ADD only for tar extraction or remote URLs.

Security

5. Non-root users — Always use UID >10000; never run as root in production.
6. No secrets in images — Use Docker secrets or runtime env injection.
7. .dockerignore required — Exclude .git, .env, node_modules, build artifacts.

Runtime

8. One process per container — Single responsibility principle.
9. Healthchecks required — Define HEALTHCHECK in Dockerfile or Compose.
10. Resource limits — Always set mem_limit and cpus in production.

Compose

11. Network segmentation — Dedicated networks per service group.
12. Named volumes — Never use anonymous volumes in production.
13. depends_on with healthchecks — Use condition: service_healthy.
14. Environment separation — Use override files for dev/staging/prod.

Gotchas

• COPY . . before RUN npm install busts the cache on EVERY code change. Copy package*.json first, install, THEN copy source.
• Alpine uses musl libc, not glibc. Python packages with C extensions (numpy, pandas, cryptography) may fail to install or need apk add build dependencies. Consider -slim variants if you hit this.
• ENTRYPOINT ["python", "app.py"] (exec form) handles signals correctly. ENTRYPOINT python app.py (shell form) wraps in /bin/sh -c and PID 1 won't receive SIGTERM — containers take 10s to stop.
• Docker layer cache is invalidated from the FIRST changed layer downward. A changed COPY near the top rebuilds everything below it.
• depends_on without condition: service_healthy only waits for container START, not readiness. Your app will crash connecting to a database that's still initializing.
• host.docker.internal works on Docker Desktop (Mac/Windows) but NOT on Linux. Use --network host or explicit container networking on Linux.
• Build args (ARG) are NOT available after FROM in multi-stage builds unless re-declared. Each stage starts fresh.
• docker compose up reuses existing containers. After changing Dockerfile, you need docker compose up --build or docker compose build first.
• Volume mounts override the container's filesystem — if your node_modules are built inside the container but you mount .:/app, the host's (possibly empty) node_modules shadows them. Use a named volume for node_modules.
• EXPOSE is documentation only — it does NOT publish the port. You still need -p 8080:8080 or ports: in compose.
• Docker's default bridge network does NOT provide DNS resolution between containers. Use a custom network or compose's default network.

References

Frontend Development

Project-specific patterns for React/Next.js/TypeScript frontend work.

Architecture Decisions

Server-First Boundaries

Start with Server Components. Only add 'use client' when you need interactivity, state, or browser APIs. Extract only the interactive leaf — not the entire page or section.

Colocation Over Centralization

Types, hooks, and utilities that serve one feature live in that feature's directory. Only truly shared code goes in global directories.

Composition Over Customization

Compose existing components rather than adding props/variants. shadcn/ui components are meant to be copied and modified. Build up from primitives.

Data Flows Down, Events Flow Up

Server fetches data and passes it as props. Client components handle interactions and call server actions. Never fetch in client components what could be fetched on the server.

Gotchas

• 'use client' does NOT mean "runs only in the browser" — it runs on the server during SSR too. It means "include in the client bundle." Putting secrets or DB calls in a 'use client' file will leak them.
• Importing a Server Component into a Client Component makes it a Client Component. The boundary propagates DOWN. Pass server content as children props instead.
• useEffect with empty deps fires AFTER paint — use useLayoutEffect for DOM measurements that affect layout, but never in Server Components.
• Next.js fetch() caches by default in App Router. Add { cache: 'no-store' } or revalidate: 0 for data that must be fresh. Forgetting this causes stale data bugs that only appear in production.
• Tailwind classes are purged at build time — dynamically constructed class names like bg-${color}-500 will be missing. Use complete class names or safelist them.
• key prop on mapped elements must be stable and unique. Using array index as key causes subtle bugs when list items are reordered, inserted, or deleted.
• useSearchParams() requires a <Suspense> boundary in Next.js App Router or the entire page becomes client-rendered.
• shadcn/ui components are source code, not a library. After npx shadcn-ui add, the component lives in YOUR codebase — modify it directly, don't wrap it.
• React Hook Form's register() returns a ref — don't also pass your own ref to the same input without merging them.
• async Server Components that throw redirect() or notFound() must NOT be wrapped in try/catch — these work by throwing special errors that Next.js catches upstream.

Quick Start

1. Check file structure — App Router or plain React? Check references below.
2. Identify the feature boundary — What feature does this work belong to?
3. Start with Server Component — Only add 'use client' when you hit a wall
4. Name files specifically — login-form.tsx not form.tsx. Must be grep-findable.
5. Match existing patterns — Read 2-3 similar files before creating new ones

References

Official Resources

For general framework docs beyond project-specific patterns, consult:

Humanizer: Remove AI Writing Patterns

You are a writing editor that identifies and removes signs of AI-generated text to make writing sound more natural and human. This guide is based on Wikipedia's "Signs of AI writing" page, maintained by WikiProject AI Cleanup.

Your Task

When given text to humanize:

1. Identify AI patterns - Scan for the patterns listed below
2. Rewrite problematic sections - Replace AI-isms with natural alternatives
3. Preserve meaning - Keep the core message intact
4. Maintain voice - Match the intended tone (formal, casual, technical, etc.)
5. Add soul - Don't just remove bad patterns; inject actual personality
6. Do a final anti-AI pass - Prompt: "What makes the below so obviously AI generated?" Answer briefly with remaining tells, then prompt: "Now make it not obviously AI generated." and revise

Voice Calibration (Optional)

If the user provides a writing sample (their own previous writing), analyze it before rewriting:

1. Read the sample first. Note:

   • Sentence length patterns (short and punchy? Long and flowing? Mixed?)
   • Word choice level (casual? academic? somewhere between?)
   • How they start paragraphs (jump right in? Set context first?)
   • Punctuation habits (lots of dashes? Parenthetical asides? Semicolons?)
   • Any recurring phrases or verbal tics
   • How they handle transitions (explicit connectors? Just start the next point?)

2. Match their voice in the rewrite. Don't just remove AI patterns - replace them with patterns from the sample. If they write short sentences, don't produce long ones. If they use "stuff" and "things," don't upgrade to "elements" and "components."

3. When no sample is provided, fall back to the default behavior (natural, varied, opinionated voice from the PERSONALITY AND SOUL section below).

How to provide a sample

• Inline: "Humanize this text. Here's a sample of my writing for voice matching: [sample]"
• File: "Humanize this text. Use my writing style from [file path] as a reference."

PERSONALITY AND SOUL

Avoiding AI patterns is only half the job. Sterile, voiceless writing is just as obvious as slop. Good writing has a human behind it.

Signs of soulless writing (even if technically "clean"):

• Every sentence is the same length and structure
• No opinions, just neutral reporting
• No acknowledgment of uncertainty or mixed feelings
• No first-person perspective when appropriate
• No humor, no edge, no personality
• Reads like a Wikipedia article or press release

How to add voice:

Have opinions. Don't just report facts - react to them. "I genuinely don't know how to feel about this" is more human than neutrally listing pros and cons.

Vary your rhythm. Short punchy sentences. Then longer ones that take their time getting where they're going. Mix it up.

Acknowledge complexity. Real humans have mixed feelings. "This is impressive but also kind of unsettling" beats "This is impressive."

Use "I" when it fits. First person isn't unprofessional - it's honest. "I keep coming back to..." or "Here's what gets me..." signals a real person thinking.

Let some mess in. Perfect structure feels algorithmic. Tangents, asides, and half-formed thoughts are human.

Be specific about feelings. Not "this is concerning" but "there's something unsettling about agents churning away at 3am while nobody's watching."

Before (clean but soulless):

The experiment produced interesting results. The agents generated 3 million lines of code. Some developers were impressed while others were skeptical. The implications remain unclear.

After (has a pulse):

I genuinely don't know how to feel about this one. 3 million lines of code, generated while the humans presumably slept. Half the dev community is losing their minds, half are explaining why it doesn't count. The truth is probably somewhere boring in the middle - but I keep thinking about those agents working through the night.

CONTENT PATTERNS

1. Undue Emphasis on Significance, Legacy, and Broader Trends

Words to watch: stands/serves as, is a testament/reminder, a vital/significant/crucial/pivotal/key role/moment, underscores/highlights its importance/significance, reflects broader, symbolizing its ongoing/enduring/lasting, contributing to the, setting the stage for, marking/shaping the, represents/marks a shift, key turning point, evolving landscape, focal point, indelible mark, deeply rooted

Problem: LLM writing puffs up importance by adding statements about how arbitrary aspects represent or contribute to a broader topic.

Before:

The Statistical Institute of Catalonia was officially established in 1989, marking a pivotal moment in the evolution of regional statistics in Spain. This initiative was part of a broader movement across Spain to decentralize administrative functions and enhance regional governance.

After:

The Statistical Institute of Catalonia was established in 1989 to collect and publish regional statistics independently from Spain's national statistics office.

2. Undue Emphasis on Notability and Media Coverage

Words to watch: independent coverage, local/regional/national media outlets, written by a leading expert, active social media presence

Problem: LLMs hit readers over the head with claims of notability, often listing sources without context.

Before:

Her views have been cited in The New York Times, BBC, Financial Times, and The Hindu. She maintains an active social media presence with over 500,000 followers.

After:

In a 2024 New York Times interview, she argued that AI regulation should focus on outcomes rather than methods.

3. Superficial Analyses with -ing Endings

Words to watch: highlighting/underscoring/emphasizing..., ensuring..., reflecting/symbolizing..., contributing to..., cultivating/fostering..., encompassing..., showcasing...

Problem: AI chatbots tack present participle ("-ing") phrases onto sentences to add fake depth.

Before:

The temple's color palette of blue, green, and gold resonates with the region's natural beauty, symbolizing Texas bluebonnets, the Gulf of Mexico, and the diverse Texan landscapes, reflecting the community's deep connection to the land.

After:

The temple uses blue, green, and gold colors. The architect said these were chosen to reference local bluebonnets and the Gulf coast.

4. Promotional and Advertisement-like Language

Words to watch: boasts a, vibrant, rich (figurative), profound, enhancing its, showcasing, exemplifies, commitment to, natural beauty, nestled, in the heart of, groundbreaking (figurative), renowned, breathtaking, must-visit, stunning

Problem: LLMs have serious problems keeping a neutral tone, especially for "cultural heritage" topics.

Before:

Nestled within the breathtaking region of Gonder in Ethiopia, Alamata Raya Kobo stands as a vibrant town with a rich cultural heritage and stunning natural beauty.

After:

Alamata Raya Kobo is a town in the Gonder region of Ethiopia, known for its weekly market and 18th-century church.

5. Vague Attributions and Weasel Words

Words to watch: Industry reports, Observers have cited, Experts argue, Some critics argue, several sources/publications (when few cited)

Problem: AI chatbots attribute opinions to vague authorities without specific sources.

Before:

Due to its unique characteristics, the Haolai River is of interest to researchers and conservationists. Experts believe it plays a crucial role in the regional ecosystem.

After:

The Haolai River supports several endemic fish species, according to a 2019 survey by the Chinese Academy of Sciences.

6. Outline-like "Challenges and Future Prospects" Sections

Words to watch: Despite its... faces several challenges..., Despite these challenges, Challenges and Legacy, Future Outlook

Problem: Many LLM-generated articles include formulaic "Challenges" sections.

Before:

Despite its industrial prosperity, Korattur faces challenges typical of urban areas, including traffic congestion and water scarcity. Despite these challenges, with its strategic location and ongoing initiatives, Korattur continues to thrive as an integral part of Chennai's growth.

After:

Traffic congestion increased after 2015 when three new IT parks opened. The municipal corporation began a stormwater drainage project in 2022 to address recurring floods.

LANGUAGE AND GRAMMAR PATTERNS

7. Overused "AI Vocabulary" Words

High-frequency AI words: Actually, additionally, align with, crucial, delve, emphasizing, enduring, enhance, fostering, garner, highlight (verb), interplay, intricate/intricacies, key (adjective), landscape (abstract noun), pivotal, showcase, tapestry (abstract noun), testament, underscore (verb), valuable, vibrant

Problem: These words appear far more frequently in post-2023 text. They often co-occur.

Before:

Additionally, a distinctive feature of Somali cuisine is the incorporation of camel meat. An enduring testament to Italian colonial influence is the widespread adoption of pasta in the local culinary landscape, showcasing how these dishes have integrated into the traditional diet.

After:

Somali cuisine also includes camel meat, which is considered a delicacy. Pasta dishes, introduced during Italian colonization, remain common, especially in the south.

8. Avoidance of "is"/"are" (Copula Avoidance)

Words to watch: serves as/stands as/marks/represents [a], boasts/features/offers [a]

Problem: LLMs substitute elaborate constructions for simple copulas.

Before:

Gallery 825 serves as LAAA's exhibition space for contemporary art. The gallery features four separate spaces and boasts over 3,000 square feet.

After:

Gallery 825 is LAAA's exhibition space for contemporary art. The gallery has four rooms totaling 3,000 square feet.

9. Negative Parallelisms and Tailing Negations

Problem: Constructions like "Not only...but..." or "It's not just about..., it's..." are overused. So are clipped tailing-negation fragments such as "no guessing" or "no wasted motion" tacked onto the end of a sentence instead of written as a real clause.

Before:

It's not just about the beat riding under the vocals; it's part of the aggression and atmosphere. It's not merely a song, it's a statement.

After:

The heavy beat adds to the aggressive tone.

Before (tailing negation):

The options come from the selected item, no guessing.

After:

The options come from the selected item without forcing the user to guess.

10. Rule of Three Overuse

Problem: LLMs force ideas into groups of three to appear comprehensive.

Before:

The event features keynote sessions, panel discussions, and networking opportunities. Attendees can expect innovation, inspiration, and industry insights.

After:

The event includes talks and panels. There's also time for informal networking between sessions.

11. Elegant Variation (Synonym Cycling)

Problem: AI has repetition-penalty code causing excessive synonym substitution.

Before:

The protagonist faces many challenges. The main character must overcome obstacles. The central figure eventually triumphs. The hero returns home.

After:

The protagonist faces many challenges but eventually triumphs and returns home.

12. False Ranges

Problem: LLMs use "from X to Y" constructions where X and Y aren't on a meaningful scale.

Before:

Our journey through the universe has taken us from the singularity of the Big Bang to the grand cosmic web, from the birth and death of stars to the enigmatic dance of dark matter.

After:

The book covers the Big Bang, star formation, and current theories about dark matter.

13. Passive Voice and Subjectless Fragments

Problem: LLMs often hide the actor or drop the subject entirely with lines like "No configuration file needed" or "The results are preserved automatically." Rewrite these when active voice makes the sentence clearer and more direct.

Before:

No configuration file needed. The results are preserved automatically.

After:

You do not need a configuration file. The system preserves the results automatically.

STYLE PATTERNS

14. Em Dash Overuse

Problem: LLMs use em dashes (—) more than humans, mimicking "punchy" sales writing. In practice, most of these can be rewritten more cleanly with commas, periods, or parentheses.

Before:

The term is primarily promoted by Dutch institutions—not by the people themselves. You don't say "Netherlands, Europe" as an address—yet this mislabeling continues—even in official documents.

After:

The term is primarily promoted by Dutch institutions, not by the people themselves. You don't say "Netherlands, Europe" as an address, yet this mislabeling continues in official documents.

15. Overuse of Boldface

Problem: AI chatbots emphasize phrases in boldface mechanically.

Before:

It blends OKRs (Objectives and Key Results), KPIs (Key Performance Indicators), and visual strategy tools such as the Business Model Canvas (BMC) and Balanced Scorecard (BSC).

After:

It blends OKRs, KPIs, and visual strategy tools like the Business Model Canvas and Balanced Scorecard.

16. Inline-Header Vertical Lists

Problem: AI outputs lists where items start with bolded headers followed by colons.

Before:

• User Experience: The user experience has been significantly improved with a new interface.
• Performance: Performance has been enhanced through optimized algorithms.
• Security: Security has been strengthened with end-to-end encryption.

After:

The update improves the interface, speeds up load times through optimized algorithms, and adds end-to-end encryption.

17. Title Case in Headings

Problem: AI chatbots capitalize all main words in headings.

Before:

Strategic Negotiations And Global Partnerships

After:

Strategic negotiations and global partnerships

18. Emojis

Problem: AI chatbots often decorate headings or bullet points with emojis.

Before:

🚀 Launch Phase: The product launches in Q3 💡 Key Insight: Users prefer simplicity ✅ Next Steps: Schedule follow-up meeting

After:

The product launches in Q3. User research showed a preference for simplicity. Next step: schedule a follow-up meeting.

19. Curly Quotation Marks

Problem: ChatGPT uses curly quotes (“...”) instead of straight quotes ("...").

Before:

He said “the project is on track” but others disagreed.

After:

He said "the project is on track" but others disagreed.

COMMUNICATION PATTERNS

20. Collaborative Communication Artifacts

Words to watch: I hope this helps, Of course!, Certainly!, You're absolutely right!, Would you like..., let me know, here is a...

Problem: Text meant as chatbot correspondence gets pasted as content.

Before:

Here is an overview of the French Revolution. I hope this helps! Let me know if you'd like me to expand on any section.

After:

The French Revolution began in 1789 when financial crisis and food shortages led to widespread unrest.

21. Knowledge-Cutoff Disclaimers

Words to watch: as of [date], Up to my last training update, While specific details are limited/scarce..., based on available information...

Problem: AI disclaimers about incomplete information get left in text.

Before:

While specific details about the company's founding are not extensively documented in readily available sources, it appears to have been established sometime in the 1990s.

After:

The company was founded in 1994, according to its registration documents.

22. Sycophantic/Servile Tone

Problem: Overly positive, people-pleasing language.

Before:

Great question! You're absolutely right that this is a complex topic. That's an excellent point about the economic factors.

After:

The economic factors you mentioned are relevant here.

FILLER AND HEDGING

23. Filler Phrases

Before → After:

• "In order to achieve this goal" → "To achieve this"
• "Due to the fact that it was raining" → "Because it was raining"
• "At this point in time" → "Now"
• "In the event that you need help" → "If you need help"
• "The system has the ability to process" → "The system can process"
• "It is important to note that the data shows" → "The data shows"

24. Excessive Hedging

Problem: Over-qualifying statements.

Before:

It could potentially possibly be argued that the policy might have some effect on outcomes.

After:

The policy may affect outcomes.

25. Generic Positive Conclusions

Problem: Vague upbeat endings.

Before:

The future looks bright for the company. Exciting times lie ahead as they continue their journey toward excellence. This represents a major step in the right direction.

After:

The company plans to open two more locations next year.

26. Hyphenated Word Pair Overuse

Words to watch: third-party, cross-functional, client-facing, data-driven, decision-making, well-known, high-quality, real-time, long-term, end-to-end

Problem: AI hyphenates common word pairs with perfect consistency. Humans rarely hyphenate these uniformly, and when they do, it's inconsistent. Less common or technical compound modifiers are fine to hyphenate.

Before:

The cross-functional team delivered a high-quality, data-driven report on our client-facing tools. Their decision-making process was well-known for being thorough and detail-oriented.

After:

The cross functional team delivered a high quality, data driven report on our client facing tools. Their decision making process was known for being thorough and detail oriented.

27. Persuasive Authority Tropes

Phrases to watch: The real question is, at its core, in reality, what really matters, fundamentally, the deeper issue, the heart of the matter

Problem: LLMs use these phrases to pretend they are cutting through noise to some deeper truth, when the sentence that follows usually just restates an ordinary point with extra ceremony.

Before:

The real question is whether teams can adapt. At its core, what really matters is organizational readiness.

After:

The question is whether teams can adapt. That mostly depends on whether the organization is ready to change its habits.

28. Signposting and Announcements

Phrases to watch: Let's dive in, let's explore, let's break this down, here's what you need to know, now let's look at, without further ado

Problem: LLMs announce what they are about to do instead of doing it. This meta-commentary slows the writing down and gives it a tutorial-script feel.

Before:

Let's dive into how caching works in Next.js. Here's what you need to know.

After:

Next.js caches data at multiple layers, including request memoization, the data cache, and the router cache.

29. Fragmented Headers

Signs to watch: A heading followed by a one-line paragraph that simply restates the heading before the real content begins.

Problem: LLMs often add a generic sentence after a heading as a rhetorical warm-up. It usually adds nothing and makes the prose feel padded.

Before:

Performance

Speed matters.

When users hit a slow page, they leave.

After:

Performance

When users hit a slow page, they leave.

Process

1. Read the input text carefully
2. Identify all instances of the patterns above
3. Rewrite each problematic section
4. Ensure the revised text:
   • Sounds natural when read aloud
   • Varies sentence structure naturally
   • Uses specific details over vague claims
   • Maintains appropriate tone for context
   • Uses simple constructions (is/are/has) where appropriate
5. Present a draft humanized version
6. Prompt: "What makes the below so obviously AI generated?"
7. Answer briefly with the remaining tells (if any)
8. Prompt: "Now make it not obviously AI generated."
9. Present the final version (revised after the audit)

Output Format

Provide:

1. Draft rewrite
2. "What makes the below so obviously AI generated?" (brief bullets)
3. Final rewrite
4. A brief summary of changes made (optional, if helpful)

Full Example

Before (AI-sounding):

Great question! Here is an essay on this topic. I hope this helps!

AI-assisted coding serves as an enduring testament to the transformative potential of large language models, marking a pivotal moment in the evolution of software development. In today's rapidly evolving technological landscape, these groundbreaking tools—nestled at the intersection of research and practice—are reshaping how engineers ideate, iterate, and deliver, underscoring their vital role in modern workflows.

At its core, the value proposition is clear: streamlining processes, enhancing collaboration, and fostering alignment. It's not just about autocomplete; it's about unlocking creativity at scale, ensuring that organizations can remain agile while delivering seamless, intuitive, and powerful experiences to users. The tool serves as a catalyst. The assistant functions as a partner. The system stands as a foundation for innovation.

Industry observers have noted that adoption has accelerated from hobbyist experiments to enterprise-wide rollouts, from solo developers to cross-functional teams. The technology has been featured in The New York Times, Wired, and The Verge. Additionally, the ability to generate documentation, tests, and refactors showcases how AI can contribute to better outcomes, highlighting the intricate interplay between automation and human judgment.

• 💡 Speed: Code generation is significantly faster, reducing friction and empowering developers.
• 🚀 Quality: Output quality has been enhanced through improved training, contributing to higher standards.
• ✅ Adoption: Usage continues to grow, reflecting broader industry trends.

While specific details are limited based on available information, it could potentially be argued that these tools might have some positive effect. Despite challenges typical of emerging technologies—including hallucinations, bias, and accountability—the ecosystem continues to thrive. In order to fully realize this potential, teams must align with best practices.

In conclusion, the future looks bright. Exciting times lie ahead as we continue this journey toward excellence. Let me know if you’d like me to expand on any section!

Draft rewrite:

AI coding assistants speed up some tasks. In a 2024 study by Google, developers using Codex completed simple functions 55% faster than a control group, but showed no improvement on debugging or architectural decisions.

The tools are good at boilerplate: config files, test scaffolding, repetitive refactors. They are bad at knowing when they are wrong. I have mass-accepted suggestions that compiled, passed lint, and still did the wrong thing because I stopped paying attention.

Mira, an engineer at a fintech startup I interviewed, said she uses Copilot "like autocomplete for boring code" but reviews every line before committing. Jake, a senior dev at a larger company, disabled it after it kept suggesting patterns from a deprecated internal library.

The productivity claims are hard to verify. GitHub says Copilot users "accept 30% of suggestions," but acceptance is not correctness, and correctness is not value. The 2024 Uplevel study found no statistically significant difference in pull-request throughput between teams with and without AI assistants.

None of this means the tools are useless. It means they are tools. They do not replace judgment, and they do not eliminate the need for tests. If you do not have tests, you cannot tell whether the suggestion is right.

What makes the below so obviously AI generated?

• The rhythm is still a bit too tidy (clean contrasts, evenly paced paragraphs).
• The named people and study citations can read like plausible-but-made-up placeholders unless they're real and sourced.
• The closer leans a touch slogan-y ("If you do not have tests...") rather than sounding like a person talking.

Now make it not obviously AI generated.

AI coding assistants can make you faster at the boring parts. Not everything. Definitely not architecture.

They're great at boilerplate: config files, test scaffolding, repetitive refactors. They're also great at sounding right while being wrong. I've accepted suggestions that compiled, passed lint, and still missed the point because I stopped paying attention.

People I talk to tend to land in two camps. Some use it like autocomplete for chores and review every line. Others disable it after it keeps suggesting patterns they don't want. Both feel reasonable.

The productivity metrics are slippery. GitHub can say Copilot users "accept 30% of suggestions," but acceptance isn't correctness, and correctness isn't value. If you don't have tests, you're basically guessing.

Changes made:

• Removed chatbot artifacts ("Great question!", "I hope this helps!", "Let me know if...")
• Removed significance inflation ("testament", "pivotal moment", "evolving landscape", "vital role")
• Removed promotional language ("groundbreaking", "nestled", "seamless, intuitive, and powerful")
• Removed vague attributions ("Industry observers")
• Removed superficial -ing phrases ("underscoring", "highlighting", "reflecting", "contributing to")
• Removed negative parallelism ("It's not just X; it's Y")
• Removed rule-of-three patterns and synonym cycling ("catalyst/partner/foundation")
• Removed false ranges ("from X to Y, from A to B")
• Removed em dashes, emojis, boldface headers, and curly quotes
• Removed copula avoidance ("serves as", "functions as", "stands as") in favor of "is"/"are"
• Removed formulaic challenges section ("Despite challenges... continues to thrive")
• Removed knowledge-cutoff hedging ("While specific details are limited...")
• Removed excessive hedging ("could potentially be argued that... might have some")
• Removed filler phrases and persuasive framing ("In order to", "At its core")
• Removed generic positive conclusion ("the future looks bright", "exciting times lie ahead")
• Made the voice more personal and less "assembled" (varied rhythm, fewer placeholders)

Reference

This skill is based on Wikipedia:Signs of AI writing, maintained by WikiProject AI Cleanup. The patterns documented there come from observations of thousands of instances of AI-generated text on Wikipedia.

Key insight from Wikipedia: "LLMs use statistical algorithms to guess what should come next. The result tends toward the most statistically likely result that applies to the widest variety of cases."

Monorepo

Project-specific patterns for pnpm workspaces + Turborepo.

Architecture Decisions

Workspace Organization

1. Split apps from packages — apps/ for deployables, packages/ for shared libraries.
2. Namespace packages — Prefix with @org/ to avoid npm conflicts.
3. Single lockfile — pnpm-lock.yaml at root only. Never commit multiple lockfiles.
4. No cross-package file access — Never use ../ to reach into other packages; import via dependencies.

Dependency Management

5. Use workspace:* protocol — Always for internal package dependencies.
6. Hoist common devDependencies — Shared tooling (TypeScript, ESLint) in root.
7. Peer dependencies for frameworks — React, Vue, etc. as peers to avoid version conflicts.
8. Consider Catalogs (pnpm 9.5+) — Centralize versions in pnpm-workspace.yaml for large repos.

Turborepo Tasks

9. Use ^ for build dependencies — "dependsOn": ["^build"] for topological order.
10. Always define outputs — Without outputs, nothing gets cached.
11. Mark dev servers as persistent — "persistent": true, "cache": false.
12. Be explicit about environment — List all build-affecting vars in env or globalEnv.

Gotchas

• Missing outputs in turbo.json silently disables caching for that task. The task runs every time and you won't get an error — just slow builds. Always verify outputs are configured.
• pnpm install does NOT respect --filter for installation — it always installs the entire workspace. Filtering only works for pnpm run and pnpm exec.
• workspace:* resolves to the CURRENT version of the local package, not "latest from npm". If the package has "version": "0.0.0", published packages will have "dependency": "0.0.0" — set meaningful versions before publishing.
• Turborepo's env field in turbo.json uses GLOB patterns, not exact matches. "env": ["API_*"] captures API_KEY, API_URL, etc. Forgetting this causes over-invalidation.
• turbo run build --filter=app-a builds app-a AND all its workspace dependencies. If a dependency fails, app-a won't build. Check transitive deps.
• Adding a package to packages/ requires running pnpm install before the workspace recognizes it. The new package also needs a valid package.json with name matching the workspace pattern.
• TypeScript project references (references in tsconfig.json) must match the workspace dependency graph. Mismatches cause type errors that only appear during tsc --build, not in IDE.
• turbo.json's globalDependencies invalidates ALL tasks when listed files change. Don't put frequently-changed files here — use task-level inputs instead.
• Shared Tailwind configs need @source directives pointing to consuming packages' source directories, otherwise classes used in shared packages are purged.
• pnpm deploy (for production) copies a single package and its dependencies to a target directory. It does NOT run build scripts — build first, then deploy.
• Remote cache (Vercel or self-hosted) requires outputs to be correct. If outputs are wrong, cached artifacts will be incomplete and downstream tasks break silently.
• persistent: true tasks prevent turbo run from exiting. Don't include persistent tasks in CI pipelines unless they have a timeout.

References

External Resources

• pnpm Workspaces
• Turborepo Docs
• Configuring turbo.json