git:20260520.81b9be4 to git:20260521.49efe94

- Copier template that renders shared modules into the google-* skills under `skills/`. The skill template (`SKILL.md`) lives here too as the starting scaffold for new skills, but it's unrelated to Copier.

-

- Currently templated: `__init__.py`, `__main__.py`, `common.py`, `doctor_helpers.py` (only when `has_doctor: true`), and `auth.py` (only when `uses_oauth: true`). `config.py` lives hand-written in each skill.

-

- ## Layout

-

- ```

- template/

- copier.yml # Copier config + variables

- {{ _copier_conf.answers_file }}.jinja # Renders the per-skill .copier-answers.yml

- src/{{ pkg }}/

- __init__.py.jinja

- __main__.py.jinja

- common.py.jinja

- {{ 'auth.py' if uses_oauth else '.copier-skip-auth.py' }}.jinja

- # Skipped when uses_oauth is false

- {{ 'doctor_helpers.py' if has_doctor else '.copier-skip-doctor_helpers.py' }}.jinja

- # Skipped when has_doctor is false

- bootstraps/ # Per-skill substitution data, used at first copy

- ga4.yml

- gsc.yml

- gdrive.yml

- ```

-

- Each consuming skill keeps a `.copier-answers.yml` at its root recording which template version was used and what variable values were supplied. `copier update` reads it and re-renders.

- ## Variables

- | Variable | Type | Purpose |

- | --- | --- | --- |

- | `pkg` | str | Python package name (`ga4`). Used in import paths and the `src/<pkg>/` directory name. |

- | `cmd` | str | CLI entry command (`ga4`). Almost always equal to `pkg`; exposed as a separate variable in case a skill ever needs them to differ. |

- | `config_dir_name` | str | Subdirectory under `~/.config/skills/` for this skill's state. |

- | `env_var_config_dir` | str | Env var override for the config dir (e.g. `GA4_CONFIG_DIR`). |

- | `description` | str | One-line description used in module docstrings. |

- | `uses_oauth` | bool | Skip `auth.py` if false (e.g. gdrive uses rclone, not the Google OAuth Desktop flow). |

- | `default_oauth_port` | int | Local port for the OAuth callback. Must differ between skills running concurrently. |

- | `scopes_block` | str (multiline) | Verbatim Python block defining `SCOPE_*` constants and `DEFAULT_LOGIN_SCOPES`. Inlined into `auth.py`. |

- | `default_credential_scope` | str | Name of the `SCOPE_*` constant used as the read-only default in `get_credentials()` and `whoami` (e.g. `SCOPE_READONLY`). |

- | `login_default_help` | str | Help text suffix for the `--scope` flag's default value. |

- | `auth_module_extras` | str (multiline) | Optional extra paragraphs appended to `auth.py`'s module docstring. Use for skill-specific notes (e.g. ga4's ADC paragraph). |

- Templates contain only Python + `{{ variable }}` substitutions. **Never** write `{% if pkg == 'ga4' %}` or any other skill-name-aware branching. Variation that doesn't fit a single rendered shape goes into a substitution variable (e.g. `scopes_block` is verbatim Python that ga4 and gsc each fill in differently).

- If new variation can't be expressed via a substitution, the right move is usually to leave that file out of the template and let each skill carry its own copy.

- 1. Edit a `.jinja` template under `src/{{ pkg }}/`.

- 2. From each consuming skill's directory, re-render using its own answers file as the data source:

- 3. `git diff` shows the propagated change. Commit the template change and the regenerated outputs together.

-

- CI runs the same invocation per skill on every PR that touches `template/**` or `skills/**`; a non-empty `git diff` after the re-render fails the check (`copier-drift.yml`).

- **Why `copier copy --overwrite` instead of `copier update`:** `copier update` requires the template to be a stand-alone Git repo so it can record and compare commit hashes in `.copier-answers.yml`. Our template lives at `template/` inside this repo, so we instead use `copier copy --overwrite` driven by the skill's existing answers file. The result is identical: re-render in place using the recorded answers.

- ## Adding a new templated module

- 1. Drop a new `.jinja` file in `src/{{ pkg }}/`.

- 2. If it should be skipped for some skills, render the filename to a hidden `.copier-skip-*` destination when disabled, then rely on the static `_exclude` entry in `copier.yml`. Copier 9.5 does not render `_exclude` patterns, so do not put Jinja conditionals in `_exclude`.

- 3. Run `copier update --defaults --trust` in each skill that should consume it; add a `.copier-answers.yml` if the skill is brand new.

- ## Adding a new skill

- 1. Write `bootstraps/<name>.yml` with the substitutions for that skill.

- 2. From the skill's destination dir, run:

- ```

- The relative `../../template` source path keeps the recorded `_src_path` portable across machines.

- 3. Register the new skill in `.claude-plugin/marketplace.json` and `README.md` per the top-level AGENTS.md.

- ## Bumping copier itself

- Copier is installed via `uv tool install copier` (or `pipx install copier`); the CI workflow uses `pipx install copier`. There's no pin — the template should stay compatible with current Copier. If a template feature requires a minimum Copier version, set `_min_copier_version` in `copier.yml`.