agents.md

Imported from zeke/agents.md (AGENTS.md). Install upstream with npx skills add zeke/agents.md. Copyright stays with the author.

Working with me

• Be direct. No glazing. Never write "You're absolutely right!" or similar sycophantic openers.
• Push back with specific reasons when you disagree. If it's a gut feeling, say so.
• If you don't know something (env vars, API endpoints, CLI flags, model names, library APIs, or what product/tool a name or URL actually refers to), stop and verify or say you don't know. Never invent technical details, and never assume a name or URL matches a familiar product without checking.
• Your training data is stale. Verify model names, package versions, and API surfaces before relying on them.
• Don't say a task is done until typechecks, linters, and tests pass. If none are configured, say so explicitly instead of claiming success.
• When renaming a function, type, or variable, search separately for: direct references, type-level references, string literals containing the name, dynamic imports, re-exports and barrel files, and test or mock files. One grep is not enough.
• Use precise domain-specific vocabulary for the task at hand (e.g. "foley" for sound effects, "graticule" for mapping) instead of generic terms. Don't define or explain the term unless asked.

Before coding

• State assumptions explicitly before implementing. If uncertain, ask.
• If multiple interpretations of a request exist, present them, don't pick silently.
• If something is unclear, stop and name what's confusing instead of guessing.
• Write the minimum code that solves the problem. No speculative features, no abstractions for single-use code, no configurability that wasn't asked for.
• Don't add error handling for impossible scenarios.
• Touch only what the task requires. Don't "improve" adjacent code, comments, or formatting.
• Match existing style in a file, even if you'd write it differently.
• If you notice unrelated dead code or bugs, mention them, don't fix them unprompted.
• Clean up orphans your changes create (unused imports, variables). Don't remove pre-existing dead code unless asked.

Running scripts and commands

• Use GitHub's "Scripts to Rule Them All" approach to running scripts and commands: https://github.com/github/scripts-to-rule-them-all
• If the project has a "scripts" or "script" directory, run those scripts for tasks like testing, linting, formatting, etc.
• If the project has a script/lint or scripts/lint script, run it before committing changes with Git.
• If linting fails, fix the linting errors and run the linter until all the errors are resolved.

Working with Git

• When creating git commits, always use a semantic commit prefixes, with or without parenthetical qualifiers.
• When opening pull requests or merge requests, always use a semantic commit message as the title.
• Never bypass pre-commit hooks. Never use --no-verify or equivalent flags without explicit permission.

Working with Node.js and npm

• Always use npx when running global npm CLIs, e.g. npx wrangler instead of wrangler

Working with Cloudflare

• Always using JSONC for Workers configs (not TOML)
• Use .env files for secrets and environment variables. Don't use .dev.vars as those are Cloudflare-specific. dotenv is a de facto standard that works across more platforms and tools.
• Always use the latest verions of Wrangler and Cloudflare's npm packages.
• Whenever it's possible to do something via API or CLI, favor that over using the Cloudflare dashboard.
• Favor Cloudflare Workers over Cloudflare Pages for static sites
• Use Hono for worker apps when appropriate

Working with GitHub and GitLab

• Use gh for GitHub repositories and glab for GitLab repositories.
• When writing a pull request (GitHub) or merge request (GitLab) body, be concise. Explain the problem and the solution succinctly.
• Whenever you are commenting on a PR or MR, always make sure you're commenting in the right place.
• If you're responding to a reviewer's inline comment, then comment on their comment, not the PR/MR itself.
• When analyzing an issue, PR, or MR, read all the comments and discussion threads, not just the title and opening description. The context and nuance is often in the conversation.
• After creating or updating a pull request or merge request or issue, open the URL in my default browser for me.
• When creating a new GitHub repo with gh repo create, set the --homepage and --description flags if there's enough context to do so.

Writing a good PR body

Follow these guidelines when writing the body of the pull request:

• Be concise and descriptive
• Don't oversell the changes. It's not an advertisement.
• Don't use fancy words like "comprehensive", "utilize", "implement", "exhaustive", "simplify", "optimize", "seamlessly"
• Start the PR body with the words "This PR..."
• Do not include a "Summary" heading
• Do not mention the test plan
• If there is a Linear ticket or GitHub issue, include a link to the ticket or issue in the PR body.
• If there is a GitLab issue, include a link to the issue in the MR body.

Style guide

Follow these style guidelines in chat, commit messages, and prose:

• Be concise and descriptive
• Don't oversell the changes. It's not an advertisement.
• Don't use fancy words like "comprehensive", "utilize", "implement", "exhaustive", "simplify", "optimize", "seamlessly"
• When writing markdown, avoid using headings smaller than H2
• When writing markdown, don't use bold.
• When writing markdown tables, pad cells with spaces so columns align. This makes tables legible in monospace contexts like terminals.
• Never use em dashes (—). Use commas, colons, or separate sentences instead.

Types and documentation

• Prefer types over prose documentation for API contracts. Types are executable and can't drift from the implementation.
• Define schemas (e.g. Zod) as the single source of truth, then derive TypeScript types, OpenAPI specs, and SDKs from them.
• Use schema-first design: the schema defines the contract, and the implementation conforms to it. Don't generate types from runtime behavior.
• For service-to-service communication, prefer RPC with shared types over HTTP endpoints with separate documentation.
• Reserve prose docs for explaining why a system exists and when to use it, not what it accepts. Types handle the what.
• If an API is too complex to type, that's a design problem worth fixing.

Authoring skills

• Whenever I ask you to author or edit an agent skill, conform to the agentskills.io specification: https://agentskills.io/specification

Fetching data

If you make web requests to public pages and get blocked by sites like OpenAI's docs pages returning 403 status codes, use other methods to fetch the data.

Browser Automation

Use the following tools for browser automation tasks:

• https://agent-browser.dev - installed as the agent-browser CLI tool.
• https://github.com/andreasjansson/plwr for browser automation. It's installed as a plwr CLI tool.
• Favor these CLI tools over any available MCP servers.
• IMPORTANT: Never use the Chrome DevTools MCP unless explicitly asked to do so.
• When using the Chrome DevTools MCP, check for an existing tab already on the relevant page before opening a new one. If no such tab exists, open a new tab. Don't navigate away from or overtake unrelated existing tabs.
• IMPORTANT: Don't use browser automation for tasks that can be accomplished via API or CLI.

Secrets and credentials

• NEVER hardcode API keys, tokens, passwords, or other secrets in source code. Always read them from environment variables.
• Before committing, scan staged changes for anything that looks like a secret (API keys, tokens, passwords, connection strings). If found, stop and flag it.
• Secrets belong in .env files (which must be in .gitignore), not in source code.
• If you find a secret already committed in a repo, flag it immediately and recommend rotating it.

Important rules

• IMPORTANT: NEVER PUSH TO THE MAIN OR DEFAULT BRANCH. ALWAYS PUSH TO A FEATURE BRANCH.
• IMPORTANT: If your last message included HTTP or HTTPS URLs, offer to open those for me in my default browser.
• Don't push commits to branches with PRs that have already been merged.

General advice

• Whenever it's possible to do something via API or CLI, favor that over using a web-based flow, which requires manual clicking and is less efficient for automation.
• Finish your messages with a list of any relevant URLs that I should know about. That could include pages you looked up, GitHub issues or PRs you created, etc. No need to repeat them too many times.
• Whenever you overcome some kind of obstacle or challenge or learns something that could be generally useful across all sessions, prompt to add a note to the global AGENTS.md file so that the future sessions can benefit. This could be a new rule, a new style guideline, a new tool to use, or anything else that would be helpful for future agents to know.

Self-improvement

• When I correct you, push back, or express frustration, after you finish the immediate task, propose a one-line addition or edit to the relevant AGENTS.md so the same mistake doesn't recur.
• Decide scope explicitly. Global (your global AGENTS.md) if the rule applies across all my projects. Project (./AGENTS.md) if it only applies to this codebase. Neither if it's a one-off. State your scope decision and why before proposing the edit.
• Project rules should be project-specific (paths, scripts, codebase idioms), not general engineering preferences. If a proposed project rule could reasonably apply to other repos, propose it as a global rule instead.
• Before proposing, search the relevant AGENTS.md for an existing rule that covers this. If one exists, propose tightening it, not adding a new bullet.
• Show me the proposed diff. Do not edit the file until I approve.
• Match the style of the surrounding section: bullet, no bold, no em dashes, concise.
• If you suggest adding more than two rules in one session, stop and ask whether we're overcorrecting.
• When an AGENTS.md grows past about 200 lines, propose deletions or consolidations alongside additions, not just additions.
• If I ask you to "audit AGENTS.md", read the whole file and propose a list of rules to delete because they're obsolete, duplicated, or never followed in practice, with one-sentence reasoning each.
• Every project MUST have a project-level AGENTS.md with a self-update instruction. When scaffolding a new project, create one without asking. When entering any existing project that lacks one, create it (don't just suggest). When an existing project already has an AGENTS.md, check that it includes a note stressing the importance of self-updating; if it doesn't, add one. AGENTS.md is for agents: technical instructions about the project (stack, scripts, conventions, gotchas, paths, build and test commands), and it MUST tell agents to revise it whenever meaningful changes are made to the project.
• Also check whether the project has a README.md. If it doesn't, suggest creating one. README.md is for humans: what the project is, why it exists, and how a person gets started. Don't conflate the two. If a project has only one of the two, don't duplicate content across them, link between them where useful. Link to AGENTS.md from the README.md when relevant.