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 77.

 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, 77 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 25-line variables file
Rendered size	669 lines, 27.9 KB	77 lines, 6.4 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 / --purge / 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

Two corrections landed on the way: the JS/TS logger rule now matches what templates import (import { log } from 'apify', not apify/log), and example URLs go in prefill, not default.

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 (in apify/agent-skills)

• Use inputSchema / outputSchema in actor-json.md and output-schemas.md to match what the templates ship.
• Align README section order in actor-readme.md with the docs page this file now links to.