# Gemma Agentic Toolkit — Repo Guidelines A Claude Code plugin marketplace containing 10 independently installable plugins with skills, agents, and scripts for the Gemma team. ## Repository structure ``` gemma-agentic-toolkit/ ├── .claude-plugin/ │ └── marketplace.json # Plugin catalog ├── plugins/ │ ├── gemma-1password/ # 1Password secret management │ ├── gemma-airflow/ # Airflow DAG management │ ├── gemma-commercial/ # Commercial, sales & PM: contracts, proposals, projects │ ├── gemma-dlt/ # dlt connector development │ ├── gemma-ewah-migration/ # EWAH → dlt migration │ ├── gemma-infra/ # Infrastructure management │ ├── gemma-kimball/ # Kimball dimensional modelling │ ├── gemma-metabase/ # Metabase dashboard QA │ ├── gemma-snowflake/ # Snowflake + tundri/Permifrost │ ├── gemma-tech-research/ # Technical research reports │ └── gemma-toolkit-ops/ # Toolkit maintenance & self-healing ├── .github/workflows/ │ ├── release-please.yml # Per-plugin semver releases │ ├── validate-plugins.yml # Structural validation on PRs │ └── claude-review.yml # AI code review with plugin rules ├── CLAUDE.md # This file └── README.md ``` ## Plugin conventions ### Plugin directory layout ``` plugins// ├── .claude-plugin/ │ └── plugin.json # Name, description, version, author, keywords ├── hooks/ # Optional: Claude Code hooks (SessionStart, PreToolUse, etc.) │ ├── hooks.json # Hook event → command mapping │ └── *.sh # Hook scripts ├── scripts/ # Optional: shared scripts (statusline, utilities) ├── skills/ │ └── / │ ├── SKILL.md # Skill definition with YAML frontmatter │ ├── scripts/ # Executable code (Python uv scripts, shell scripts) │ ├── assets/ # Templates, configs, workflow files │ └── references/ # Supplementary documentation ├── agents/ # Optional: sub-agent definitions (.md with YAML frontmatter) └── references/ # Optional: shared reference docs across skills ``` ### Runtime variables - **`${CLAUDE_SKILL_DIR}`** — resolves to the current skill's directory at runtime. Use in SKILL.md to reference scripts and assets. - **`${CLAUDE_PLUGIN_ROOT}`** — resolves to the plugin's root directory at runtime. Use in hooks and shared scripts that live outside a specific skill. ### plugin.json ```json { "name": "gemma-", "description": "One-liner", "version": "1.0.0", "author": { "name": "Gemma Analytics" }, "repository": "https://github.com/Gemma-Analytics/gemma-agentic-toolkit", "license": "MIT", "keywords": ["tag1", "tag2"] } ``` - `name` must match the plugin directory name exactly - `version` must be valid semver — release-please auto-bumps it ### Release-please registration (required) Every new plugin **must** be registered in both release-please files, or it won't get semver tags/releases. CI enforces this. 1. **`release-please-config.json`** — add the plugin under `packages`: ```json "plugins/": { "component": "", "extra-files": [ { "type": "json", "path": ".claude-plugin/plugin.json", "jsonpath": "$.version" } ] } ``` 2. **`.release-please-manifest.json`** — add the initial version: ```json "plugins/": "1.0.0" ``` ### SKILL.md format ```yaml --- name: skill-folder-name description: One-sentence description of what this skill does. disable-model-invocation: true # Required for task skills with side effects argument-hint: "[arg-name]" # If skill accepts parameters context: fork # If skill should run in a forked context --- # Skill Title Full skill content in Markdown... ``` - `name` must match the skill folder name (kebab-case) - `description` is used by agents for skill discovery - **`disable-model-invocation: true`** is required on all task skills with side effects (`setup-*`, `create-*`, `migrate-*`, `trigger-*`, `run-*`, `containerize-*`, `contribute-*`, `rotate-*`, `generate-*`) - Reference/cookbook skills that Claude should auto-load must NOT have `disable-model-invocation: true` - Scripts must be referenced with `${CLAUDE_SKILL_DIR}/scripts/...` — bare relative paths break after installation - Skills accepting parameters must use `$ARGUMENTS` in the body - SKILL.md should be under 500 lines — extract detailed content to `references/` ### Audit orchestrator skills (the audit contract) The shared `claude-audit.yml` reusable workflow in `Gemma-Analytics/.github` can run **any** plugin's orchestrator skill on a schedule and open a report PR — it stays audit-type-agnostic by relying on one contract. A skill is drivable by that workflow when it: - sets `disable-model-invocation: true` and `argument-hint: "[path-to-]"` (where `` names what the skill audits — e.g. `repo-root`, `dbt-project`, `airflow-dags`), and accepts `$ARGUMENTS` as that target directory (defaulting to the current working directory); - **auto-detects** which sub-checks apply and records skipped ones with a reason; - is **read-only** — never modifies the audited repo, and never runs anything that returns warehouse data (e.g. `dbt show`) or reads secrets; - writes a single dated Markdown report whose summary section heading is **`## Executive summary`** (matched case-insensitively) — the workflow extracts that block for the PR body. Examples that satisfy it: `gemma-deployment-security/generate-security-report`, `gemma-dbt/validate-repo`. To add a new audit type, ship such a skill and add a thin caller in the target repo — no workflow change. (Full details + caller examples: the `docs/claude-audit.md` doc in the `.github` repo.) ### Agent definition format ```yaml --- name: agent-name description: When to use this agent tools: Read, Grep, Glob, Bash model: sonnet | opus | haiku | inherit --- System prompt and instructions in Markdown... ``` - `name` must match the file name (kebab-case) - `tools` lists allowed tools (comma-separated) - See [Claude Code sub-agents reference](https://code.claude.com/docs/en/sub-agents) --- ## General conventions - **Placeholders:** Use `` with snake_case - **Python scripts:** Always use the `uv` standalone script pattern (`#!/usr/bin/env -S uv run --script` with inline `# /// script` metadata) - **No tool-specific syntax** in content — no Cursor frontmatter, no `@file` references, no XML tags - **Supporting files** go in `scripts/`, `assets/`, or `references/` — not loose in the feature folder - **Kebab-case** for all folder names --- ## Commit conventions This repo uses [Conventional Commits](https://www.conventionalcommits.org/) with release-please monorepo support. Each plugin has independent semver versioning. ### Format ``` (): ``` - **`type`** determines the version bump: - `feat` → minor (1.0.0 → 1.1.0) - `fix` → patch (1.0.0 → 1.0.1) - `feat!` or `BREAKING CHANGE` footer → major (1.0.0 → 2.0.0) - **`scope`** is the plugin name: `gemma-dlt`, `gemma-snowflake`, `gemma-kimball`, etc. - **`description`** is imperative, lowercase, no period ### Examples ``` feat(gemma-dlt): add incremental loading support to rest-api-source skill fix(gemma-snowflake): correct keypair rotation for MFA accounts feat(gemma-kimball): add SaaS retention analysis templates docs(gemma-metabase): update Playwright authentication examples chore(ci): update validate-plugins workflow ``` ### Semver rules - **MAJOR**: breaking change to skill behavior, removed skills, renamed skills - **MINOR**: new skills added, new features in existing skills - **PATCH**: bug fixes, wording improvements, reference updates