Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
git clone --depth 1 https://github.com/nottelabs/notte-skillsWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/rules/nottelabs/notte-skills/notte-best-practices)<a href="https://agentmods.dev/rules/nottelabs/notte-skills/notte-best-practices"><img src="https://agentmods.dev/badge/rules/nottelabs/notte-skills/notte-best-practices/github.svg" alt="Measured on agentmods" height="20"></a>Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.
<a href="https://agentmods.dev/rules/nottelabs/notte-skills/notte-best-practices"><img src="https://agentmods.dev/badge/rules/nottelabs/notte-skills/notte-best-practices.svg" alt="Reviewed on agentmods" width="80" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00013 | $0.00928 |
| Opus 5 | $0.00006 | $0.00464 |
| Sonnet 5 | $0.00003 | $0.00186 |
| Haiku 4.5 | $0.00001 | $0.00093 |
Grade A, and why
notte-best-practices scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 3d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
What it actually says
- always use
Sessionas a context manager (with client.Session() as session: ...) so the cloud browser is released; never leak sessions across requests. - prefer
client.scrape(url=...)over an agent when the task is "read this URL and give me X". Agents cost 5–10x more per run. - when the user wants structured output, define a Pydantic model and pass it as
response_formattoagent.runorclient.scrape. Don't parse free-text answers. - script the deterministic parts with
session.execute(type=...)and only hand the ambiguous step to the agent. This is Notte's biggest reliability + cost win. - put
solve_captchas=Trueandproxies=TrueonSession, neverAgent— onAgentthey silently do nothing. Captcha solving is already the default, soproxies=Trueis the one that changes anything when a site blocks you. - store credentials in
client.Vault()— never paste them into the agent'staskstring. They will leak into logs. notte(local) andnotte_sdk(hosted) are two different imports, not aliases. Don't mix them in one file.reasoning_modelis a LiteLLM model string ("gemini/gemini-2.5-flash"), not a provider name, and must be one the platform advertises — runnotte agents start --helpfor the current list rather than inventing one.- file storage is session-scoped and available automatically. The removed SDK keywords
use_file_storageandenable_file_storageraise aTypeError; usestorage=...only to supply aRemoteFileStorageinstance. The CLI no longer exposes file-storage session flags; its file commands are session-scoped. - sessions close after 3 minutes idle or 15 minutes total by default. Raise
--idle-timeout-minutes/--max-duration-minutesfor anything slow, or the next command fails with an unexplainedSession closed. - the trailing module-level
run()call in a Function file is optional — the runtime invokesrun()itself, so keeping or removing it makes no difference.notte sessions workflow-codeemits one; leave it as-is. - never put
from __future__ import annotationsin a Function file — it breaksresponse_formatwithPydanticUserError: Model is not fully defined. notte functions runblocks until the run finishes, so it is bounded by the global--timeout(default 60s). Raise it for slow Functions instead of assuming the Function is broken.- judge a run on
result, notstatus: an error raised insiderun()can still reportstatus: "closed". - to find pages, use
notte search— it hits the search API directly and does not need a browser session. Reserve sessions for interacting with a page. - before building a new Function, check the
anything-apimarketplace (searchtool, or https://anything.notte.cc/marketplace) — someone may already have published one. max_stepsis a hard stop. If the agent runs out, raise it rather than rephrasing the task.- the second time a task runs successfully and the page hasn't changed, promote it to a Notte Function for fast/cheap deterministic reruns.
- when creating a reusable Notte Function from browser automation, first test the flow interactively with CLI session commands, then run
notte sessions workflow-codeand use the exported script as the base. Capture the session ID; if the session is stopped or no longer current, export withnotte sessions workflow-code --session-id <session-id>. Export first for interactive, stateful, or authenticated flows, where the working sequence and session options are hard to reconstruct; for a stateless Function over a JSON endpoint or fixed HTML structure you already confirmed, writing that request directly is fine. - after a successful agent run,
agent.workflow.code()returns a deterministic Python script you can deploy as a Function with no LLM tokens per invocation. session.observe()is required beforesession.execute(type="click"|"fill", id=...). Re-observe after navigation or major page changes.
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 3d ago Changed 52f3bc586342
- 9d ago First seen · 27 lines · 13 tokens per session scan A bb3077daf3c6
notte-best-practices is a cursor rule published in the GitHub repository nottelabs/notte-skills (11 stars, last pushed 4d ago), licensed MIT. It adds 13 tokens to every session and 928 once invoked, about $0.0001 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other cursor rules, from other repositories
001-camofox-core
Core camofox-browser concepts — element refs, snapshot-first workflow, server basics.
real-browser-mcp
Instructions for using Real Browser MCP to control the user's actual browser.
invictum-browser
Use Invictum Browser Bridge whenever the user requests IBB, IBG, Invictum Browser Bridge, or Invictum Browser Gate.
ponytail
Ponytail, lazy senior dev mode. Always pick the simplest solution that works.
angular-20
This rule provides comprehensive best practices and coding standards for Angular development, focusing on modern TypeScript, standalone components, signals, and performance optimizations.
dev-standard
Apache Superset development standards and guidelines for Cursor IDE.