docs(agent-bases): render one lean AGENTS.md into all templates

[patrikbraborec]

Summary

Every template's AGENTS.md is now rendered from one source instead of three hand-synced copies, and it shrinks from 669 lines to 79.

 agent-bases/
-├── js.AGENTS.md          # 669 lines, 27.9 KB
-├── ts.AGENTS.md          # same file, TS snippets
-├── python.AGENTS.md      # same file, Python snippets
+├── AGENTS.md             # single source, {{placeholders}} for language-specific values
+└── languages.json        # placeholder values per prefix: js, ts, python
 scripts/
 └── copy-agents-md-to-templates.mts   # renders + Prettier-formats per template
 templates/
 ├── js-*/AGENTS.md        # 44 rendered files, 78–79 lines each
 ├── ts-*/AGENTS.md
 └── python-*/AGENTS.md

How it renders

flowchart LR
    S["agent-bases/AGENTS.md"] --> R["copy-agents-md-to-templates.mts<br/>(runs in pnpm run build)"]
    L["agent-bases/languages.json"] --> R
    R -->|"fill {{entry}}, {{logger}}, ..."| F["prettier.format(markdown)"]
    F --> T1["templates/js-*/AGENTS.md"]
    F --> T2["templates/ts-*/AGENTS.md"]
    F --> T3["templates/python-*/AGENTS.md"]
    T1 & T2 & T3 -.->|"@AGENTS.md"| C["CLAUDE.md"]

Loading

The script throws on a placeholder that languages.json does not define, and formats the rendered output so table alignment survives values of different lengths.

Why

AGENTS.md is loaded into the agent's context on every turn. Current guidance (Claude Code docs, agents.md, Red Hat) keeps it to always-true guidance under ~150 lines and pushes task-specific procedures into skills or links. The ETH Zurich evaluation of AGENTS.md found that verbose context files lower task success and raise cost by over 20%.

The old file also duplicated, and had drifted from, the apify-actor-development skill in apify/agent-skills. After agent-skills#87 the two disagreed on dataset schema rules (fields: {} vs. a full superset with nullable), on default vs. prefill for example URLs, and on README section order.

	Before	After
Source files	3, edited by hand in parallel	1 + a 35-line variables file
Rendered size	669 lines, 27.9 KB	79 lines, 6.6 KB
Schema rules	inlined, out of date	linked: skill + docs URLs
Rules phrasing	11 "do not" bullets	positive statements

What the new file keeps

AGENTS.md
├── Commands        # apify run / validate-schema / push / actors search (+ generate-schema-types for TS)
├── Workflow        # 6 steps, each with a done-condition
├── Rules           # logger, SDK-over-CLI, untrusted content, crawler choice, aborting event, APIFY_TOKEN, standby
├── Ask first       # installs, apify push, proxy, Dockerfile, deleting storages
└── Reference       # install hint for apify-actor-development skill + docs URL table

Corrections that landed on the way:

• The JS/TS logger rule matches what templates import (import { log } from 'apify', not apify/log).
• Example URLs go in prefill, not default.
• Rules name the Python crawler (BeautifulSoupCrawler / ParselCrawler), dataset call (dataset.get_info()), and aborting handler (Actor.on(Event.ABORTING, ...)) instead of the JS ones; languages.json carries them.
• The apify validate-schema comment says what it checks. CLI 1.10 validates the input, dataset, and key-value store schemas but skips an outputSchema, because it reads only the deprecated output key. Passing it is the output-schema done-condition, and the template's "fields": {} is marked as a placeholder.

What it drops

Inlined input / output / dataset / key-value store specifications, the logging level list, the README section list, the project tree, the Playwright MCP JSON, the Do/Don't lists, and the two Crawlee gotchas (requestHandlerTimeoutMillis, additionalHttpHeaders) that agent-skills#87 flagged as unverifiable.

Verification

• pnpm run lint passes.
• pnpm run format:check passes for all tracked files.
• pnpm run test-without-templates passes (17 tests).
• No unrendered {{ placeholders in any template.

Follow-up

• Use inputSchema / outputSchema in actor-json.md and output-schemas.md, done in agent-skills#87 together with the logger, Python entry point, and standby fixes.
• In apify/agent-skills: align README section order in actor-readme.md with the docs page this file now links to.

[l2ysho]

This is really too big to carefully check, I guess lets LGTM (lets gamble this merge) and lets watch how agents like it. We can revert anytime.

[patrikbraborec]

@l2ysho yes, but before merge I want to run some evals :)