boilerplate - SKILL.md Agent Skill

name: boilerplate version: 1.1.0 description: > Documents the template inventory and variable contract behind scaffold-cli.py — which Jinja2 template renders with which variables for each site profile. Use during Phase 2 scaffolding when choosing scaffold flags or understanding what the generated boilerplate contains. The scaffold-cli.py script is the primary path. user-invocable: false

Boilerplate Generator (Template-Driven)

Primary method: run the v2 scaffold script — it renders everything below deterministically and writes a .manifest.json provenance file:
python ${CLAUDE_PLUGIN_ROOT}/scripts/scaffold-cli.py <app>/agent-harness \
  --app-name <app> \
  --protocol <rest|graphql|html-scraping|batchexecute> \
  --http-client <httpx|curl_cffi> \
  --auth-type <none|cookie|api-key|google-sso> \
  --resource <name> [--resource <name> ...] \
  [--has-polling] [--has-context] [--has-partial-ids]
Requires pip install jinja2 (TEMPLATE_VERSION 2.1.0). Each repeatable --resource flag scaffolds a commands/<resource>.py module.

If the script is unavailable, do NOT render templates by hand from memory — follow skills/shared/RECOVERY.md §scaffold-cli.py Unavailable (adapt from the newest generated CLI, e.g., capitoltrades/agent-harness/).

All templates live in ${CLAUDE_PLUGIN_ROOT}/templates/*.tpl (Jinja2 syntax). Generated code must satisfy skills/shared/CONVENTIONS.md — the templates already encode those rules; never "simplify" them away.

Step 1: Collect Template Variables

Variable	Type	Source	Example
`app_name`	str	CLI name (`cli-web-<app>` → `<app>`)	`hackernews`
`APP_NAME`	str	UPPER_SNAKE (hyphens → underscores first)	`HACKERNEWS`
`AppName`	str	PascalCase	`HackerNews`
`protocol`	enum	traffic-analysis.json: `rest`, `graphql`, `html-scraping`, `batchexecute`	`rest`
`http_client`	enum	protection detection: `httpx`, `curl_cffi`	`httpx`
`auth_type`	enum	site profile: `none`, `cookie`, `api-key`, `google-sso`	`cookie`
`resources`	list[str]	`<APP>.md` endpoint groups (one `--resource` flag each)	`stories users`
`has_polling`	bool	async/long-running operations exist	`false`
`has_context`	bool	CLI needs `use <id>` / `status` context	`false`
`has_partial_ids`	bool	resource IDs support prefix matching	`false`

Casing is derived inside the templates via Jinja2 filters — you only supply --app-name.

Step 2: Template → Output Map

Template (`templates/`)	Output	Rendered when
`exceptions.py.tpl`	`core/exceptions.py`	always
`client_rest_httpx.py.tpl`	`core/client.py`	`http_client=httpx`, non-batchexecute (GraphQL/HTML variants are `{% if %}` blocks inside)
`client_rest_curl.py.tpl`	`core/client.py`	`http_client=curl_cffi`, non-batchexecute
`client_batchexecute.py.tpl`	`core/client.py`	`protocol=batchexecute`
`auth.py.tpl` (UNIFIED)	`core/auth.py`	`auth_type != none` — google-sso specifics (cookie domain priority, regional forcing) are a `{% if auth_type == "google_sso" %}` block; there is no separate Google template
`cli_entry.py.tpl`	`<app>_cli.py` (+ `__main__.py`)	always — REPL default, UTF-8 fix, `--json` propagation
`command_group.py.tpl`	`commands/<resource>.py`	once per `--resource` flag — Click group skeleton wired to the client
`helpers.py.tpl`	`utils/helpers.py`	always (`handle_errors`, `print_json`)
`helpers_polling.py.tpl`	appended to helpers	`--has-polling`
`helpers_context.py.tpl`	appended to helpers	`--has-context`
`helpers_partial_ids.py.tpl`	appended to helpers	`--has-partial-ids`
`output.py.tpl`	`utils/output.py`	always (`json_success`/`json_error`)
`setup.py.tpl`	`setup.py`	always — namespace packages, entry point, deps per `http_client`/`protocol`
`conftest.py.tpl`	`tests/conftest.py`	always
`test_e2e.py.tpl`	`tests/test_e2e.py`	always — `_resolve_cli` + `TestCLISubprocess` fixtures pre-wired
`rpc_types.py.tpl`, `rpc_encoder.py.tpl`, `rpc_decoder.py.tpl`	`core/rpc/`	`protocol=batchexecute` only
`README.md.tpl`	`cli_web/<app>/README.md` skeleton	always
`SKILL.md.tpl`	per-CLI skill skeleton	always (filled in during Phase 4)

Also produced by the script (not templates): __init__.py files, the vendored runtime adapters utils/repl_skin.py, utils/doctor.py, and utils/mcp_server.py (canonical source cli-web-core/cli_web_core/, synced by cli-web-devkit resync; the entry point registers doctor + mcp-serve from them), utils/config.py, and .manifest.json at the harness root recording template_version, profile (protocol/http_client/auth), resources, and generation timestamp — fleet tooling (cli-web-devkit drift) depends on it.

Step 3: Profile Recipes

Site profile	Flags
No-auth + read-only (HN, gh-trending)	`--auth-type none` — NO auth.py, NO session.py, NO auth commands (dead code is a checklist FAIL)
No-auth + CRUD (Dev.to)	`--auth-type api-key` — minimal auth module, `auth set-key`
Cookie auth (reddit, linkedin)	`--auth-type cookie` + `--has-polling` if generation ops exist
Google SSO + RPC (notebooklm, stitch)	`--auth-type google-sso --protocol batchexecute` — renders `rpc/` subpackage + Google block in auth.py
Anti-bot protected (Cloudflare/WAF)	`--http-client curl_cffi` — see `capture/references/protection-detection.md` escalation ladder
Stateful apps (notebooks/projects)	add `--has-context`; UUID-keyed resources add `--has-partial-ids`

Step 4: Post-Scaffold Checklist

.manifest.json exists at the harness root with template_version: 2.1.0
cli_web/ has NO __init__.py; cli_web/<app>/ HAS one
No unresolved Jinja2 markers ({{, {%) remain in any output file
FILL_IN_BASE_URL markers noted — replace during implementation
auth_type=none → no core/auth.py, no auth command group anywhere
protocol=batchexecute → core/rpc/ has types/encoder/decoder; otherwise core/rpc/ does NOT exist
One commands/<resource>.py exists per --resource flag, all registered on the CLI group
All files pass python -m py_compile

Then continue with methodology/SKILL.md Step B: fill in endpoint methods in client.py from <APP>.md, flesh out the scaffolded command modules, and keep _print_repl_help() in sync (CONVENTIONS.md §REPL Rules).