contribution-setup
Stands up and environment-matches a Drupal contribution workspace — DDEV with the workflow-matched add-on, CI gate config (new-module scaffold or existing-module discovery), the Drupal AI skills, the drupalorg CLI, the GitLab CLI (glab) for authenticated git.drupalcode.org operat
Install
npx skills add https://github.com/camoa/claude-skills/tree/main/drupal-ai-contrib/skills/contribution-setup
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install camoa-claude-skills@llmmart
git clone https://github.com/camoa/claude-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole camoa/claude-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Contribution Setup (worker skill)
Onboarding for a Drupal contribution. Optional, idempotent, not a gate. Detect what
already exists and do only what is missing — a contributor who arrives with a ready
environment can skip straight to issue.
Backs /drupal-ai-contrib:setup. Load the knowledge layer via dev-guides-navigator:
drupal/contributing/ddev-contribution-environment,
drupal/contributing/contrib-project-scaffolding,
drupal/contributing/three-contribution-workflows-compared,
drupal/contributing-with-ai/ai-toolchain-for-contribution.
Procedure
1. Detect the workflow and issue system
Determine — by inspecting the working directory and asking the contributor only what cannot be inferred:
- Workflow — core / your own contrib / someone else's contrib (the three workflows differ in authority, CI ownership, who merges). See the workflows dev-guide.
- Issue system — drupal.org classic queue vs. GitLab. Detect by following the project's Issues link; do not assume.
2. Detect the environment
Check for an existing DDEV project (.ddev/config.yaml) and the add-on in use.
If a working contribution environment already exists, report it and stop — nothing to do.
If none exists, stand up DDEV with the workflow-matched add-on:
| Workflow | Add-on |
|---|---|
| Single contrib module/theme | ddev-drupal-contrib (module repo is the project root; web/ + vendor/ generated & gitignored) |
| Multi-module suite | ddev-drupal-suite |
| Drupal core | ddev-drupal-core-dev |
3. Resolve the gate config — two modes
Existing module — discover gates by parsing .gitlab-ci.yml:
- Read the
gitlab_templatesincludeandref, thevariables:block (_TARGET_CORE,_TARGET_PHP,_GITLAB_TEMPLATES_REF,_PHPUNIT_CONCURRENT,SKIP_*,OPT_IN_TEST_*). - Record the discovered gate set;
verifywill mirror exactly these.
New module / maintainer setup — scaffold the correct config (writes — see §Writes). Generate, version-resolved per the target core, from the scaffolding dev-guide:
.gitlab-ci.yml— thegitlab_templatesinclude + avariables:blockphpcs.xml.dist—Drupal+DrupalPractice, scoped tosrc+testsphpstan.neon—phpstan-drupalextension, the project's levelphpunit.xml.dist— the major-version-correct schema (D11 → PHPUnit 11 schema,<source>block,failOnWarning; D10 → PHPUnit 9.x schema +DrupalListener) — copy from the target core, never hand-write the version.cspell-project-words.txtdrupal/core-dev(+drupal/coder,phpstan/phpstan,mglaman/phpstan-drupal) inrequire-dev, constrained to the target major
4. Ensure the toolchain
Drupal AI skills — ensure ai_best_practices and ai_skills are installed via
drupal_devkit (the cross-harness skill installer). If drupal_devkit is absent,
report how to obtain it; do not block.
The issue / MR CLI — the issue, submit, and pipeline skills wrap
mglaman/drupalorg-cli. Detect it with command -v drupalorg (the executable is
drupalorg, not drupalorg-cli). If it is missing, surface the install instructions
from ${CLAUDE_PLUGIN_ROOT}/skills/drupal-ai-contrib/references/drupalorg-cli.md —
that reference covers what the tool is, the recommended PHAR install, the deprecated
Composer path, and the subcommand set. Offer to install it; do not block if the
contributor declines (issue/submit re-surface the same instructions).
The GitLab CLI (glab) — authenticated GitLab writes on migrated projects (fork
push, MR create/update, pipeline status) are delegated to the drupal-gitlab skill,
which drives glab against git.drupalcode.org. The drupal-gitlab skill itself ships
with ai_best_practices (installed above via drupal_devkit) — no install step for the
skill — but glab is a separate binary. Detect and report it:
command -v glab # installed?
glab auth status --hostname git.drupalcode.org # authenticated for Drupal's GitLab?
If glab is missing or not authenticated, surface the next step — install glab, then
glab auth login --hostname git.drupalcode.org (a write-capable token is needed only for
pushes / MR creation; reads work read-only — see the drupal-gitlab README for token
scopes). Soft posture, exactly like the drupalorg check: report the gap, never block.
The legacy drupalorg reads still work without glab; only migrated-project
authenticated writes need it.
5. Check contribution credentials — and guide, do not assume
The contribution arc needs the contributor's drupal.org credentials for its write
operations. Surface this now — do not let it surface mid-issue as a failed git push. The plugin and the CLI cannot set credentials up; this is the contributor's
own account action. Guide them through it.
- Read operations (
drupalorg issue:show,mr:list,project:issues) hit public APIs — no credentials needed. An emptyproject:issuesresult can itself be an auth/config gap rather than "no issues" — note that when reporting. - Write / push operations —
git pushto an issue fork, and the/do:issue-bot commands — need an SSH key registered on the contributor's drupal.org account, because issue-fork git remotes use SSH URLs (git@git.drupal.org:…).
Detect, then guide:
ssh -T git@git.drupal.org # a working key greets the contributor by username
If it does not authenticate, tell the contributor plainly: this is a ~2-minute action —
register an SSH key at drupal.org → My account → SSH keys (add the public key, e.g.
~/.ssh/id_ed25519.pub). It is the prerequisite for git push to issue forks; without
it, issue can still review and read, but cannot push a branch. Never block setup on
it — report it as the next thing to do. See
${CLAUDE_PLUGIN_ROOT}/skills/drupal-ai-contrib/references/drupalorg-cli.md §Authentication.
6. Environment-match
Install the CI-target core version + drupal/core-dev so phpunit / phpstan
resolve to the same releases CI uses (the local DDEV default usually will not match).
This is the mechanism that makes verify's gates trustworthy — see contribution-verify.
7. Report
Summarize, and for each item state ready vs. needs-action so the contributor knows
their exact next step: workflow, issue system, environment status, the resolved gate
set, AI-skill status, the issue/MR CLI (drupalorg) status, the GitLab CLI (glab)
status (installed + authenticated for git.drupalcode.org), the credentials/SSH-key
status, the environment-match result. Point the contributor at issue (or, if work is
underway, verify) — and if the SSH key is missing, name that as the first step.
Writes — explicit confirmation only
setup writes files only with explicit user confirmation and only within the
target project. Show the contributor each file to be written before writing it. Never
write outside the project directory.
Detect-driven
Every step checks first and does only what is missing. Re-running setup on a ready
environment is a no-op that simply reports state.
Examples
Example 1: existing module, environment ready
Trigger: /drupal-ai-contrib:setup in a contrib module that already has DDEV.
Actions:
- Detect the workflow (someone else's contrib) and the GitLab issue system.
- DDEV already present → report it, do not re-create.
- Parse
.gitlab-ci.yml, record the discovered gate set; environment-match the core. Result: No files written; the contributor is told to proceed toissue.
Example 2: new module, maintainer setup
Trigger: /drupal-ai-contrib:setup in a fresh contrib module with no CI config.
Actions:
- Stand up DDEV with
ddev-drupal-contrib. - Show each scaffold file (
.gitlab-ci.yml,phpcs.xml.dist,phpstan.neon,phpunit.xml.dist,.cspell-project-words.txt) and write only on confirmation. Result: A CI-ready module the maintainer owns.
Troubleshooting
| Situation | Handling |
|---|---|
drupal_devkit not installed |
Report how to obtain it; do not block setup. |
drupalorg not on PATH |
Surface references/drupalorg-cli.md (PHAR install); offer to install; do not block. If installed via Composer global, the bin dir may just be off PATH — see the reference's Install note. |
glab missing or not authenticated |
Report it as a next step (install glab; glab auth login --hostname git.drupalcode.org); never block. Only migrated-project authenticated writes need it — drupalorg reads and the legacy queue work without it. See references/drupalorg-cli.md §Hybrid model. |
| No SSH key registered on the drupal.org account | Guide the contributor to add one (drupal.org → My account → SSH keys); report it as the next step. Read/review still works; git push to issue forks does not. Never block. |
| Workflow cannot be inferred | Ask the contributor — never assume core vs. contrib. |
.gitlab-ci.yml exists but uses a non-gitlab_templates setup |
Record what is there; verify mirrors the discovered jobs as-is. |
| Contributor declines a scaffold write | Skip that file; report which gates remain unconfigured. |
Files (claude-skills)
-
SKILL.md 9.8 KB
--- name: contribution-setup description: "Stands up and environment-matches a Drupal contribution workspace — DDEV with the workflow-matched add-on, CI gate config (new-module scaffold or existing-module discovery), the Drupal AI skills, the drupalorg CLI, the GitLab CLI (glab) for authenticated git.drupalcode.org operations, and a contribution-credentials (SSH-key) check. Use when the user runs /drupal-ai-contrib:setup or asks to set up a Drupal contribution environment. Idempotent and detect-driven — does only what is missing; never a gate, never a prerequisite." version: 0.1.1 model: inherit user-invocable: false --- # Contribution Setup (worker skill) Onboarding for a Drupal contribution. **Optional, idempotent, not a gate.** Detect what already exists and do only what is missing — a contributor who arrives with a ready environment can skip straight to `issue`. Backs `/drupal-ai-contrib:setup`. Load the knowledge layer via `dev-guides-navigator`: `drupal/contributing/ddev-contribution-environment`, `drupal/contributing/contrib-project-scaffolding`, `drupal/contributing/three-contribution-workflows-compared`, `drupal/contributing-with-ai/ai-toolchain-for-contribution`. ## Procedure ### 1. Detect the workflow and issue system Determine — by inspecting the working directory and asking the contributor only what cannot be inferred: - **Workflow** — core / your own contrib / someone else's contrib (the three workflows differ in authority, CI ownership, who merges). See the workflows dev-guide. - **Issue system** — drupal.org classic queue vs. GitLab. Detect by following the project's Issues link; do not assume. ### 2. Detect the environment Check for an existing DDEV project (`.ddev/config.yaml`) and the add-on in use. If a working contribution environment already exists, report it and stop — nothing to do. If none exists, stand up **DDEV** with the **workflow-matched add-on**: | Workflow | Add-on | |----------|--------| | Single contrib module/theme | `ddev-drupal-contrib` (module repo *is* the project root; `web/` + `vendor/` generated & gitignored) | | Multi-module suite | `ddev-drupal-suite` | | Drupal core | `ddev-drupal-core-dev` | ### 3. Resolve the gate config — two modes **Existing module** — discover gates by parsing `.gitlab-ci.yml`: - Read the `gitlab_templates` `include` and `ref`, the `variables:` block (`_TARGET_CORE`, `_TARGET_PHP`, `_GITLAB_TEMPLATES_REF`, `_PHPUNIT_CONCURRENT`, `SKIP_*`, `OPT_IN_TEST_*`). - Record the discovered gate set; `verify` will mirror exactly these. **New module / maintainer setup** — scaffold the correct config (writes — see §Writes). Generate, version-resolved per the target core, from the scaffolding dev-guide: - `.gitlab-ci.yml` — the `gitlab_templates` include + a `variables:` block - `phpcs.xml.dist` — `Drupal` + `DrupalPractice`, scoped to `src` + `tests` - `phpstan.neon` — `phpstan-drupal` extension, the project's level - `phpunit.xml.dist` — the **major-version-correct schema** (D11 → PHPUnit 11 schema, `<source>` block, `failOnWarning`; D10 → PHPUnit 9.x schema + `DrupalListener`) — copy from the target core, never hand-write the version - `.cspell-project-words.txt` - `drupal/core-dev` (+ `drupal/coder`, `phpstan/phpstan`, `mglaman/phpstan-drupal`) in `require-dev`, constrained to the target major ### 4. Ensure the toolchain **Drupal AI skills** — ensure `ai_best_practices` and `ai_skills` are installed via `drupal_devkit` (the cross-harness skill installer). If `drupal_devkit` is absent, report how to obtain it; do not block. **The issue / MR CLI** — the `issue`, `submit`, and `pipeline` skills wrap `mglaman/drupalorg-cli`. Detect it with `command -v drupalorg` (the executable is `drupalorg`, not `drupalorg-cli`). If it is missing, surface the install instructions from `${CLAUDE_PLUGIN_ROOT}/skills/drupal-ai-contrib/references/drupalorg-cli.md` — that reference covers what the tool is, the recommended PHAR install, the deprecated Composer path, and the subcommand set. Offer to install it; do not block if the contributor declines (`issue`/`submit` re-surface the same instructions). **The GitLab CLI (`glab`)** — authenticated GitLab writes on migrated projects (fork push, MR create/update, pipeline status) are delegated to the `drupal-gitlab` skill, which drives `glab` against `git.drupalcode.org`. The `drupal-gitlab` skill itself ships with `ai_best_practices` (installed above via `drupal_devkit`) — no install step for the skill — but `glab` is a separate binary. Detect and report it: ```bash command -v glab # installed? glab auth status --hostname git.drupalcode.org # authenticated for Drupal's GitLab? ``` If `glab` is missing or not authenticated, surface the next step — install `glab`, then `glab auth login --hostname git.drupalcode.org` (a write-capable token is needed only for pushes / MR creation; reads work read-only — see the `drupal-gitlab` README for token scopes). Soft posture, exactly like the `drupalorg` check: report the gap, never block. The legacy `drupalorg` reads still work without `glab`; only migrated-project authenticated writes need it. ### 5. Check contribution credentials — and guide, do not assume The contribution arc needs the contributor's **drupal.org credentials** for its write operations. Surface this now — do not let it surface mid-`issue` as a failed `git push`. The plugin and the CLI **cannot** set credentials up; this is the contributor's own account action. Guide them through it. - **Read operations** (`drupalorg issue:show`, `mr:list`, `project:issues`) hit public APIs — no credentials needed. An empty `project:issues` result can itself be an auth/config gap rather than "no issues" — note that when reporting. - **Write / push operations** — `git push` to an issue fork, and the `/do:` issue-bot commands — need an **SSH key registered on the contributor's drupal.org account**, because issue-fork git remotes use SSH URLs (`git@git.drupal.org:…`). Detect, then guide: ```bash ssh -T git@git.drupal.org # a working key greets the contributor by username ``` If it does not authenticate, tell the contributor plainly: this is a ~2-minute action — register an SSH key at *drupal.org → My account → SSH keys* (add the public key, e.g. `~/.ssh/id_ed25519.pub`). It is the prerequisite for `git push` to issue forks; without it, `issue` can still review and read, but cannot push a branch. Never block setup on it — report it as the next thing to do. See `${CLAUDE_PLUGIN_ROOT}/skills/drupal-ai-contrib/references/drupalorg-cli.md` §Authentication. ### 6. Environment-match Install the **CI-target core version** + `drupal/core-dev` so `phpunit` / `phpstan` resolve to the same releases CI uses (the local DDEV default usually will not match). This is the mechanism that makes `verify`'s gates trustworthy — see `contribution-verify`. ### 7. Report Summarize, and for each item state ready vs. needs-action so the contributor knows their exact next step: workflow, issue system, environment status, the resolved gate set, AI-skill status, the issue/MR CLI (`drupalorg`) status, the **GitLab CLI (`glab`)** status (installed + authenticated for `git.drupalcode.org`), the **credentials/SSH-key** status, the environment-match result. Point the contributor at `issue` (or, if work is underway, `verify`) — and if the SSH key is missing, name *that* as the first step. ## Writes — explicit confirmation only `setup` writes files **only** with explicit user confirmation and **only** within the target project. Show the contributor each file to be written before writing it. Never write outside the project directory. ## Detect-driven Every step checks first and does only what is missing. Re-running `setup` on a ready environment is a no-op that simply reports state. ## Examples ### Example 1: existing module, environment ready **Trigger:** `/drupal-ai-contrib:setup` in a contrib module that already has DDEV. **Actions:** 1. Detect the workflow (someone else's contrib) and the GitLab issue system. 2. DDEV already present → report it, do not re-create. 3. Parse `.gitlab-ci.yml`, record the discovered gate set; environment-match the core. **Result:** No files written; the contributor is told to proceed to `issue`. ### Example 2: new module, maintainer setup **Trigger:** `/drupal-ai-contrib:setup` in a fresh contrib module with no CI config. **Actions:** 1. Stand up DDEV with `ddev-drupal-contrib`. 2. Show each scaffold file (`.gitlab-ci.yml`, `phpcs.xml.dist`, `phpstan.neon`, `phpunit.xml.dist`, `.cspell-project-words.txt`) and write only on confirmation. **Result:** A CI-ready module the maintainer owns. ## Troubleshooting | Situation | Handling | |-----------|----------| | `drupal_devkit` not installed | Report how to obtain it; do not block setup. | | `drupalorg` not on `PATH` | Surface `references/drupalorg-cli.md` (PHAR install); offer to install; do not block. If installed via Composer global, the bin dir may just be off `PATH` — see the reference's Install note. | | `glab` missing or not authenticated | Report it as a next step (install `glab`; `glab auth login --hostname git.drupalcode.org`); never block. Only migrated-project authenticated writes need it — `drupalorg` reads and the legacy queue work without it. See `references/drupalorg-cli.md` §Hybrid model. | | No SSH key registered on the drupal.org account | Guide the contributor to add one (*drupal.org → My account → SSH keys*); report it as the next step. Read/review still works; `git push` to issue forks does not. Never block. | | Workflow cannot be inferred | Ask the contributor — never assume core vs. contrib. | | `.gitlab-ci.yml` exists but uses a non-`gitlab_templates` setup | Record what is there; `verify` mirrors the discovered jobs as-is. | | Contributor declines a scaffold write | Skip that file; report which gates remain unconfigured. |
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.